Troubleshoot Docker Teranode
Last modified: 28-April-2026
Use the quickstart scripts first. They keep checks consistent with the Docker
Compose files and .env used by the deployment.
First Checks
From the quickstart repository root:
./status.sh
./logs.sh blockchain
./logs.sh assetIf the stack is not running:
./start.shIf .env is missing:
./setup.shContainer Health
Show all services:
docker compose psInspect a health check:
docker inspect --format='{{json .State.Health}}' blockchainUse service logs for failures:
./logs.sh <service-name>Common services include blockchain, asset, rpc, legacy, p2p,
postgres, aerospike, redpanda, prometheus, and grafana.
FSM Stuck in INIT
The startup FSM transition can race while services become healthy. Set the state manually:
./cli.sh setfsmstate --fsmstate RUNNING
./cli.sh getfsmstateThen check status:
./status.shRPC Fails
Use the wrapper first:
./rpc.sh getblockchaininfoIf it fails:
- Confirm
rpc_userandrpc_passare set in.env. - Confirm the
rpccontainer is running withdocker compose ps. - Check RPC logs with
./logs.sh rpc. - Remember that quickstart binds RPC to
127.0.0.1:9292.
Port Already in Use
Check which process owns the port:
lsof -i :9292Quickstart’s common host ports are:
| Port | Service |
|---|---|
8090 | Asset viewer |
8000 | Asset cache |
9905 | P2P |
9292 | RPC, loopback only |
3005 | Grafana, loopback only |
9090 | Prometheus, loopback only |
8080 | Kafka Console, loopback only |
Change bindings in the Compose files only when you understand the security impact.
Full Mode Reachability Fails
Check .env:
listen_mode=full
asset_httpPublicAddress=https://node.example.com/api/v1
p2p_advertise_addresses=/dns4/node.example.com/tcp/9905Then verify:
- DNS points to the expected host.
- The reverse proxy forwards HTTPS asset API traffic to port
8000. - The firewall allows inbound TCP on port
9905. HOST_IPallows the reverse proxy or firewall path to reach the quickstart host binding.
Rerun startup or the reachability helper after changes:
./start.sh
./lib/reachability.shAerospike Out of Space
The quickstart Aerospike Community Edition configuration uses a bounded local UTXO store. If Aerospike reports device-full or stop-writes errors:
- Check host disk and memory.
- Confirm pruning settings were not increased unexpectedly.
- Consider reseeding from a newer snapshot if appropriate.
- For larger mainnet capacity, plan a custom Aerospike layout outside the basic quickstart defaults.
Grafana Shows No Data
Prometheus needs time to scrape initial metrics. If dashboards remain empty:
docker compose ps prometheus
./logs.sh prometheusOpen Prometheus locally at http://localhost:9090 and check target health.
Reset Bad Local State
If containers are healthy but local data is inconsistent, reset Docker volumes:
./stop.sh
./clean.sh --data-only
./start.shFor seeded recovery, run ./seed.sh before ./start.sh. See
Sync Docker Teranode.
Report Issues
Open quickstart orchestration issues in bsv-blockchain/teranode-quickstart.
Open Teranode service bugs in bsv-blockchain/teranode.