These are issues specific to deploying SigNoz on Docker (Compose or Swarm). For installation steps, see the Docker install guide.
Compose tooling not found
Cause: neither 'docker-compose' nor the 'docker compose' plugin is available means you are deploying with flavor: compose but no Compose tooling was found.
Resolution: install the Compose v2 plugin (it ships with Docker Desktop and modern Docker Engine). Foundry accepts either docker compose (the v2 plugin) or the legacy docker-compose binary, and prefers the plugin.
Swarm mode is not active
Cause: docker swarm is not active (state: inactive) means you are deploying with flavor: swarm but Swarm mode is off.
Resolution: initialize Swarm on the node you deploy from:
docker swarm init
Deploying from a non-manager node
Cause: current node is a swarm worker, not a manager. docker stack deploy only runs from a Swarm manager.
Resolution: run foundryctl from a manager node. Check which nodes are managers:
docker node ls # MANAGER STATUS column shows Leader / Reachable
Compose file not found
Cause: compose file does not exist at path: ... means you ran cast before generating the deployment. cast deploys what forge writes under pours/.
Resolution: let cast do both, or generate first:
foundryctl cast -f casting.yaml # runs gauge, forge, then deploys
# or, step by step
foundryctl forge -f casting.yaml
If your pours live in a non-default directory, point to it with -p ./my-pours.
A container is unhealthy or the UI does not load
Resolution: inspect the workload and follow the logs of the component that is failing:
# Compose
docker ps -a
docker compose -f pours/deployment/compose.yaml logs -f signoz-signoz-0
# Swarm (services are prefixed with the stack name)
docker stack services signoz
docker service logs signoz_signoz-signoz-0 -f
Docker Swarm starts services in parallel and does not honor depends_on, so dependent services may restart a few times until ClickHouse and Postgres are ready. That is expected; persistent failures are not.
A ClickHouse bootstrap container hangs fetching the histogram binary
Cause: on first start, the signoz-telemetrystore-clickhouse-user-scripts job downloads a helper binary (histogram-quantile) from GitHub, and ClickHouse waits on it. A slow or blocked connection to GitHub stalls it.
Resolution: check its logs, then give it time or restart the stack so it retries:
docker compose -f pours/deployment/compose.yaml logs signoz-telemetrystore-clickhouse-user-scripts
docker compose -f pours/deployment/compose.yaml restart
On Docker Swarm the service is signoz_signoz-telemetrystore-clickhouse-user-scripts; re-run foundryctl cast -f casting.yaml to redeploy it.
Containers keep restarting
Resolution: increase the memory allocated to Docker. SigNoz needs at least 4GB.
