Skip to main content

Common Errors and Solutions

This section details common error messages and provides clear, actionable steps to resolve them.

Sync and Performance​

Stalling during snapshot sync (0 B/s download rate)​

  • Error Description: The sync process appears to be stuck, showing a download rate of 0B/s, even with peers.
  • Cause: The RPC daemon or a connected consensus client may be "spamming" the Erigon node with requests, which interferes with the snapshot sync. This issue is still present in recent versions.
  • Solution: Temporarily disable the RPC by removing flags like --http and --ws, or stop your consensus client until the initial snapshot sync stage is complete.

Sync is extremely slow or the node is constantly falling behind​

  • Error Description: The node is not keeping up with the blockchain tip despite a fast internet connection.
  • Cause: This is almost always a disk-related problem. The read/write speed and latency of your storage device are the most significant performance bottlenecks for Erigon.
  • Solution: Upgrade your storage to a high-end NVMe SSD. Avoid using HDDs, network drives, or slow consumer-grade SSDs. See Hardware Requirements and Performance Tricks.

Node falls behind the tip after running for weeks​

  • Error Description: A node that has been healthy for weeks gradually stops keeping up with the chain tip, sometimes after the mutable database has grown large.
  • Cause: Over time the mutable chaindata database can accumulate state that slows chain-tip processing.
  • Solution: Delete only the hot database — datadir/chaindata — and restart (do not delete the whole datadir, which would force a full re-sync). Erigon re-derives chaindata from the immutable snapshots (re-downloading them if needed) and resyncs the post-snapshot tip from the consensus layer — treat it as a chain-tip resync, not an instant rebuild, and keep a backup if fast recovery matters. Make sure you are on the latest release: Erigon 3.4+ ships a much smaller chaindata and an improved pruning algorithm that greatly reduces this problem. See Optimizing Storage.

Node stuck in a "bad block" / "invalid block" forkchoice loop​

  • Error Description: The node repeatedly logs invalid block ... gas used by execution and bad block as forkchoice, and stops advancing the chain head.
  • Cause: Corrupted state in the mutable database, typically left over from an incorrect unwind, prevents the node from validating new blocks.
  • Solution: Wipe datadir/chaindata (not the entire datadir) and restart on the latest patch release, which is the reliable recovery. If it recurs immediately, running with the USE_STATE_CACHE=false environment variable is a known temporary workaround. If you can still reproduce it on the latest release, open a GitHub issue with your full <datadir>/logs/erigon.log attached.

Memory and Resources​

Out of Memory (OOM) or unexpected process termination​

  • Error Description: The Erigon process is abruptly terminated by the operating system, often with an OOM-kill event in the system logs (code=killed, status=9/KILL).

  • Cause: This can be a genuine memory leak or, more commonly, a symptom of a disk I/O bottleneck. When the disk can't keep up with processing, memory usage can balloon as the system tries to buffer data. Erigon and the Go runtime also size their memory and CPU use from the resources they can see, so on a shared or memory-constrained host they may reserve more than is safe.

  • Solution: Ensure your system meets the recommended RAM requirements in Hardware Requirements. To make Erigon more conservative on constrained hosts, set a hard memory ceiling and throttle the runtime:

    # Export the runtime tunables, then pass --batchSize as an Erigon flag:
    export GOMEMLIMIT=26GiB               # cap total Go heap (set below your physical/container limit)
    export GOGC=80                        # collect garbage more aggressively
    export GOMAXPROCS=$(( $(nproc) / 2 )) # show Erigon fewer cores → smaller RAM estimates

    erigon --batchSize=256m ...           # smaller execution batch buffer

    A clean shutdown and restart can often resolve a transient event. If the problem persists, check your dmesg logs and consider upgrading your disk. See Performance Tricks for related tuning.

Database​

Database corruption after an unexpected shutdown​

  • Error Description: The Erigon process fails to start or crashes immediately after a power outage or a forced kill.
  • Cause: Erigon's database can be corrupted if it is not shut down gracefully, which prevents the final writes from being committed.
  • Solution: The most reliable solution is to delete the corrupted datadir and re-sync from scratch. This is often faster than attempting to repair the database.

Permissions and Access​

Permission denied or Access Denied errors on startup​

  • Error Description: The process fails to access the datadir, logs, or other files.
  • Cause: The user or service account running Erigon does not have the correct file permissions for the data directory.
  • Solution: Use the chown and chmod commands to ensure the correct user account has ownership and full read/write access to the datadir. See Security for service account best practices.

Permission denied inside Docker (UID/GID mismatch)​

  • Error Description: When running the official Docker image, Erigon fails to read or write files in the mounted datadir with a permission denied error.
  • Cause: The container runs the Erigon process as UID/GID 1000. If the host directory is owned by a different user, the process cannot access it.
  • Solution: On the host, change ownership of the datadir to UID/GID 1000: sudo chown -R 1000:1000 /your/datadir. Alternatively, pass --user $(id -u):$(id -g) to docker run to run the container with your host user's identity. See Docker Compose.

Network and Configuration​

Connect: connection refused or dial tcp... failures​

  • Error Description: The node cannot connect to a component it dials out to, such as a separately run sentry or downloader, or the core instance an external RPC daemon talks to.
  • Cause: This is a configuration error. The dependent service is either not running, or the command-line flag naming its address points somewhere wrong.
  • Solution: Confirm that the required services are running and that the address flags for the components you run separately are correct — for example --sentry.api.addr, --downloader.api.addr, or --private.api.addr for an external RPC daemon. Note that --externalcl is a switch, not an address: it only disables the embedded Caplin, after which the external consensus client connects inbound to Erigon's Engine API (--authrpc.addr / --authrpc.port) rather than Erigon dialling out to it. See Configuring Erigon for all available flags.

Chain-Specific Issues​

Build and Installation​

libsilkworm_capi.so: missing shared library​

  • Error Description: Erigon fails to start with a dynamic linker error about a missing libsilkworm_capi.so shared library.
  • Cause: The binary was built with Silkworm support but the shared library is not present in the system's library path or alongside the binary.
  • Solution: Ensure the libsilkworm_capi.so file is located in the same directory as the erigon binary, or add its location to LD_LIBRARY_PATH. If you built from source, run make erigon again to confirm the library was compiled and placed correctly. See Installation for build-from-source instructions. Official Docker images bundle the library automatically.
Last updated on