Node Troubleshooting

This guide covers the most common issues operators hit when running a Base node from the official Docker setup, with steps to diagnose and resolve each one.

General troubleshooting

Before chasing specific issues, work through these baseline checks.

1. Inspect container logs. Tail the relevant container with docker compose logs -f <service_name>:

   • L2 client (Reth): docker compose logs -f execution
   • Rollup node: docker compose logs -f node. Look for errors, warnings, or repeated messages.

2. Check container status. Confirm the right containers are running with docker compose ps. Restart loops or exited containers warrant a log review.

3. Watch resource usage. CPU, RAM, disk I/O, and network usage are common bottlenecks. htop, iostat, and iftop are useful starting points.

4. Verify RPC endpoints. Use curl to confirm the L2 client’s RPC is responding (see running a Base node). Confirm L1 endpoints are correct and reachable from the node host.

5. Check the L1 node. Ensure the configured L1 execution and consensus clients are fully synced, healthy, and accessible. L1 issues block L2 sync.

Common issues

Setup and configuration

• Issue: The Docker command (docker compose up ...) fails.

  • Check: Is Docker (and Docker Compose) installed and the daemon running?
  • Check: Are you in the correct directory (the cloned node directory containing docker-compose.yml)?
  • Check: Command syntax — typos in NETWORK_ENV or CLIENT are common.

• Issue: A container fails to start with .env or environment variable errors.

  • Check: Did you set the L1 endpoints (OP_NODE_L1_ETH_RPC, OP_NODE_L1_BEACON) in the right .env file (.env.mainnet or .env.sepolia)?
  • Check: Is OP_NODE_L1_BEACON_ARCHIVER set if your configuration or L1 node requires it?
  • Check: Is OP_NODE_L1_RPC_KIND set correctly for your L1 provider?
  • Check: (Reth) Are RETH_CHAIN and RETH_SEQUENCER_HTTP correctly configured in .env?

• Issue: JWT secret or auth errors between op-node and the L2 client.

  • Check: Avoid hand-editing OP_NODE_L2_ENGINE_AUTH or the JWT file path ($OP_NODE_L2_ENGINE_AUTH) unless you know what you are doing — docker-compose handles this automatically.

• Issue: Permission errors against the data volume (./reth-data).

  • Check: The user running docker compose must have write access to the cloned repo so Docker can write into ./reth-data. Avoid sudo-running Docker commands; instead, add your user to the docker group.

Syncing

• Issue: The node never starts syncing or block height stalls.

  • Check: op-node logs for L1 endpoint or L2 client connection errors.
  • Check: Execution client logs for Engine API issues on port 8551 or P2P errors.
  • Check: L1 node health — is it accessible and fully synced?
  • Check: System time. Run ntp or chrony; significant clock drift breaks P2P.

• Issue: Sync is unusually slow.

  • Check: Hardware against the performance tuning recommendations, especially RAM and NVMe SSD. Disk I/O is usually the bottleneck.
  • Check: L1 RPC responsiveness. A slow L1 node throttles L2 sync.
  • Check: Network bandwidth and connection quality.
  • Check: op-node and L2 client logs for performance warnings or errors.

• Issue: optimism_syncStatus (port 7545 on op-node) reports a large time delta or errors.

  • Action: Inspect rollup node and L2 execution client logs around the time of the check to identify the cause (often L1 connectivity or L2 client problems).

• Issue: Error: nonce has already been used when sending transactions.

  • Cause: The node is still catching up to the chain head.
  • Action: Wait for full sync. Track progress via optimism_syncStatus or logs.

Performance

• Issue: High CPU, RAM, or disk I/O usage.
  • Check: Hardware against the performance tuning recommendations, and upgrade if needed. Local NVMe SSDs are critical.
  • Check: Client logs for specific bottlenecks or errors.

Snapshot restoration

Refer to the Snapshots guide for the canonical procedure.

• Issue: wget fails or the snapshot download is corrupted.

  • Check: Network connectivity.
  • Check: Available disk space.
  • Action: Retry the download and verify the URL.

• Issue: tar extraction fails.

  • Check: Downloaded file integrity.
  • Check: Available disk space — extraction needs much more than the download itself.
  • Check: tar command syntax.

• Issue: The node fails to start after restoring a snapshot, with database errors or missing files.

  • Check: Did you run docker compose down before touching the data directory?
  • Check: Did you remove the contents of the old data directory (./reth-data/*) before extracting and moving the new data?
  • Check: Is the chain data directly inside ./reth-data rather than in a nested folder (for example, ./reth-data/reth/...)? Verify the structure.

• Issue: Out of disk space during download or extraction.

  • Action: Free space or attach a larger volume. Use the storage formula:

    (2 * chain_size + snapshot_size + 20% buffer)

Networking and connectivity

• Issue: RPC or WS connection refused (e.g., curl localhost:8545 fails).

  • Check: Is the L2 client container running (docker compose ps)?
  • Check: Are you using the correct port (8545 HTTP, 8546 WS by default)?
  • Check: L2 client logs — did the RPC server fail to start?
  • Check: Are --http.addr and --ws.addr set to 0.0.0.0 in the client config or entrypoint so external connections work within the Docker network?

• Issue: Low peer count.

  • Check: P2P port accessibility. Ensure 30303 (TCP/UDP) and 9222 (TCP/UDP for Reth discv5) are not blocked by firewalls on the host or upstream network.
  • Check: Node logs for P2P errors.
  • Action: Behind NAT, set --nat=extip:<your-ip> via ADDITIONAL_ARGS in .env (see advanced configuration).

• Issue: Port conflicts in logs or docker compose up fails.

  • Check: Other host services using the default ports (8545, 8546, 8551, 6060, 7545, 30303):

    sudo lsof -i -P -n | grep LISTEN
    sudo netstat -tulpn | grep LISTEN

  • Action: Stop the conflicting service or remap the Base container ports in docker-compose.yml, then update the related variables ($RPC_PORT, $WS_PORT, etc.) in .env.

Getting more help

If you have worked through this guide and the issue persists:

• Discord: Join the Base Discord and post in #node-operators with details of your setup, the issue, and relevant logs.
• GitHub: Browse the Base Node repository issues, or open a new one if you suspect a bug.