Troubleshooting

Use the first error and the startup context, not only the process exit code. Record the Zebra version, network, effective configuration, selected state path, and the last height that advanced. The startup log includes build and state-format metadata; see Startup and sync.

Configuration does not load or take effect

Generate the reference without overwriting the active file:

zebrad generate --output-file zebrad-defaults.toml

A listener cannot bind

The bind error names the endpoint and requested address; the P2P message starts with Opening Zcash network protocol listener.

For an address-in-use error, identify the conflicting listener on Linux:

ss -ltnp

Stop the conflicting process or choose a distinct address for that endpoint; each listener has its own port setting.

For an unavailable-address error, choose an address assigned to the host or container. Without IPv6 support, use an IPv4 listener:

[network]
listen_addr = "0.0.0.0:8233"

This example listens on all IPv4 interfaces for Mainnet; use the network’s P2P port or an explicit alternate port. Do not expose administrative endpoints to work around a bind error.

The database is locked or cannot open

• Database likely already open: another writer or an I/O error prevents opening state. Check services, containers, and manually started nodes. Stop the existing writer or give the second node a distinct [state] cache_dir and listeners. If no writer exists, check permissions and storage health. Do not delete RocksDB’s LOCK file; wait for the owner to exit before modifying state.
• Permission denied creating or Opening database: check access to the parent directories and write permission on the cache root. In containers, check the mounted volume and effective UID/GID; see Docker ownership handling.

Disk space is exhausted

The error No space left on device means that a write or directory creation cannot complete. On Linux, check both capacity and available inodes on the filesystem containing the cache. Replace the path below with an existing cache directory:

df -h /path/to/zebra-cache
df -i /path/to/zebra-cache

Stop Zebra before moving its database. Free unrelated files or move the cache to storage with sufficient free space, then update [state] cache_dir and any environment or mount overrides. Do not delete individual RocksDB files to make room: they form one database.

Keep room for growth and maintenance; snapshot restoration also needs space for both the archive and extracted state.

Sync is slow or stalled

The syncer retries downloads and sync rounds automatically; waiting to restart sync does not request a process restart. Check current_height and time_since_last_state_block for continued progress.

For initial sync can't download and verify the genesis block or chain updates have stalled, match the accompanying evidence:

Limit resource contention

For CPU or logging contention, use a release build and remove temporary debug filters. In builds that retain debug instrumentation, restrict it to the component under investigation:

[tracing]
filter = "info,zebra_network=debug"

Default release builds compile out debug and trace events; a filter cannot restore them. See compiled log levels.

Queued blocks consume memory, and concurrent verification competes for CPU. Choose sync concurrency limits for measured capacity rather than raising every limit.

For a bandwidth-constrained node, reduce download concurrency before changing verification limits:

[sync]
download_concurrency_limit = 25

Measure height advancement and resource use before and after a change; use metrics. Zebra raises limits below the minimum bounds and logs the adjustment.

Linux TCP tuning for block propagation

Linux enables net.ipv4.tcp_slow_start_after_idle by default. It reduces a TCP connection’s congestion window after an idle period defined by the current retransmission timeout. When peers are idle between block requests, this restart can limit subsequent block-transfer throughput. Zebra checks the setting on Linux and warns at startup when it is nonzero.

Inspect the effective setting:

sysctl net.ipv4.tcp_slow_start_after_idle

To retain the congestion window across idle periods, set:

sudo sysctl -w net.ipv4.tcp_slow_start_after_idle=0

This setting affects all TCP users in the network namespace, not only Zebra. Review other workloads before changing it. To persist it for the host, put this line in /etc/sysctl.d/99-zebra-network.conf:

net.ipv4.tcp_slow_start_after_idle=0

Apply persistent host settings with sudo sysctl --system. See the Linux TCP sysctl reference for the kernel behavior.

Running Zebra in Docker

Apply the setting in the network namespace containing Zebra. With Docker’s separate container networking, add --sysctl net.ipv4.tcp_slow_start_after_idle=0 to the docker run options. With --network=host, configure the host instead; Docker does not allow network sysctl overrides in host-network mode. Changing only the host setting is not a substitute for configuring an existing separate container network namespace. See Docker’s sysctl rules.

Known limitation: private peer addresses

Zebra does not reject private IP addresses merely because they are private. It can connect to them and distribute peer addresses; filtering them by default remains tracked in issue #3117.

Use network-level egress controls if the node must not reach internal services. Do not rely on the public Zcash network configuration to isolate a node from private address ranges.

Build and test resource failures

For compilation memory exhaustion, reduce Cargo build parallelism:

export CARGO_BUILD_JOBS=2

This limits build jobs, not node threads. For test resource contention, limit nextest’s test concurrency separately:

cargo nextest run --locked --test-threads=2

For CI’s nextest profiles, follow continuous integration.

For unreliable external connectivity, set SKIP_NETWORK_TESTS=1 to skip tests that use Zebra’s network-test guard. It does not skip every network-dependent test or disable IPv6 tests. Unset it before claiming network-test coverage.

Reporting a persistent failure

Include the recorded version, network, configuration, first error, and surrounding logs in a bug report. Redact RPC cookies, credentials, wallet information, and private infrastructure details before publishing logs. For suspected vulnerabilities, follow the security policy instead of opening a public issue.