Troubleshooting

This troubleshooting guide includes step-by-step instructions that should resolve most installation issues.

Troubleshooting Docker Standalone Installation of SigNoz

1. Before you install SigNoz on Docker Standalone, ensure that all prerequisites are met.
2. Run the docker ps command and ensure that the signoz-clickhouse and signoz-signoz containers are running. If these containers are not running, increase the memory allocated to Docker.
3. If you don't see any data in the front-end, please wait two or three minutes.
4. Run the install.sh script again. The script will try to reinstall the containers that failed.
5. Follow the steps for uninstalling SigNoz section and then install SigNoz again by following the steps in the Install SigNoz on Docker Standalone section.
6. If you're still facing issues trying to install SigNoz, please reach out to us on Slack

Troubleshooting ClickHouse container crashes

If the clickhouse container is unable to start due to certain reasons, it is recommended to take the following steps before recreating the container

1. In the deploy/docker folder, run the following command to see more detailed logs for the ClickHouse container:

sudo docker-compose ps -a

This will show you the status of all containers, including ClickHouse.

• Verify system resources: Ensure your system has enough resources (CPU, memory, disk space) to run the ClickHouse container.

• Check permissions: Make sure you have the necessary permissions to run Docker containers. Try running the installation script with sudo privileges.

• Review Docker configuration: Ensure your Docker installation is up-to-date and properly configured.

2. If the logs mention about Permission denied error, it is likely due to the correct permissions not set for the container.
3. Use the chown command to change the ownership for the files that clickhouse container is unable to access.
4. If neither of this works, run the install.sh script again as the root user or by using sudo as a prefix.

Troubleshooting Ingestion

If you’ve installed SigNoz but aren’t seeing telemetry (traces, metrics, logs):

• Verify the OTLP endpoint and protocol your apps/collectors use: gRPC on port 4317 or HTTP on port 4318.
• Ensure TLS settings match the endpoint. For non‑TLS endpoints, some SDKs require enabling insecure mode (for example, OTEL_EXPORTER_OTLP_INSECURE=true).
• Check timeouts and compression. Increase timeouts for large payloads and enable gzip for reliability.
• Review application and collector logs for export errors or connection issues.
• Confirm network/firewall/DNS allow traffic to your SigNoz OTLP endpoint.

Use the address grid to quickly pick the right endpoint for your setup:

• Collector Address Grid: Self‑Hosted Ingestion – Collector Address Grid

Container signoz-init-clickhouse Hangs Forever

After installation, you might see sometime the signoz-init-clickhouse being stuck and from the logs it's shows:

docker logs signoz-init-clickhouse
# Fetching histogram-binary for linux/amd64
# Connecting to github.com (20.205.243.166:443)

This indicates the helper binary wasn’t fetched from GitHub. For these issues you should, restart the SigNoz containers and allow time for the helper binary to download:

docker compose restart