> ## Documentation Index
> Fetch the complete documentation index at: https://base-a060aa97-fix-dead-service-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Troubleshooting

> Solutions to common issues when setting up and running a Base node, covering sync problems, networking, snapshots, and performance.

This guide covers common issues encountered when setting up and running a Base node using the official [Base Node Docker setup](https://github.com/base/node) and provides steps to diagnose and resolve them.

## General Troubleshooting Steps

Before diving into specific issues, here are some general steps that often help:

1. **Check Container Logs**: This is usually the most informative step. Use `docker compose logs -f <service_name>` to view the real-time logs for a specific container.
   * 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**: Ensure the relevant Docker containers are running: `docker compose ps`. If a container is restarting frequently or exited, check its logs.

3. **Check Resource Usage**: Monitor your server’s CPU, RAM, disk I/O, and network usage. Performance issues are often linked to insufficient resources. Tools like `htop`, `iostat`, and `iftop` can be helpful.

4. **Verify RPC Endpoints**: Use `curl` to check if the L2 client’s RPC endpoint is responding (see [Running a Node](/base-chain/node-operators/run-a-base-node#running-a-node)). Also, verify your L1 endpoints are correct and accessible from the node server.

5. **Check L1 Node**: Ensure your configured L1 node (Execution and Consensus) is fully synced, healthy, and accessible. Issues with the L1 node will prevent the L2 node from syncing correctly.

***

## Common Issues and Solutions

### Setup & Configuration Issues

* **Issue**: Docker command fails (`docker compose up ...`)
  * **Check**: Is Docker and Docker Compose installed and the Docker daemon running?
  * **Check**: Are you in the correct directory (the cloned `node` directory containing `docker-compose.yml`)?
  * **Check**: Syntax errors in the command (e.g., misspelled `NETWORK_ENV`).

* **Issue**: Container fails to start, logs show errors related to `.env` files or environment variables.
  * **Check**: Did you correctly configure the L1 endpoints (`BASE_NODE_L1_ETH_RPC`, `BASE_NODE_L1_BEACON`) in the correct `.env` file (`.env.mainnet` or `.env.sepolia`)?
  * **Check**: Are `RETH_CHAIN` and `RETH_SEQUENCER_HTTP` correctly set in the `.env` file?

* **Issue**: Errors related to JWT secret or authentication between `base-consensus` and the execution client.
  * **Check**: Ensure you haven't manually modified the `BASE_NODE_L2_ENGINE_AUTH` variable or the JWT file path (`$BASE_NODE_L2_ENGINE_AUTH`) unless you know what you're doing. The `docker-compose` setup usually handles this automatically.

* **Issue**: Permission errors related to data volumes (`./reth-data`).
  * **Check**: Ensure the user running `docker compose` has write permissions to the directory where the `node` repository was cloned. Docker needs to be able to write to `./reth-data`. Sometimes running Docker commands with `sudo` can cause permission issues later; try running as a non-root user added to the `docker` group.

### Syncing Problems

* **Issue**: Node doesn't start syncing or appears stuck (block height not increasing).
  * **Check**: `base-consensus` logs. Look for errors connecting to L1 endpoints or the execution client.
  * **Check**: Look at logs for the execution client. Look for errors connecting to `base-consensus` via the Engine API (port `8551`) or P2P issues.
  * **Check**: L1 node health and sync status. Is the L1 node accessible and fully synced?
  * **Check**: System time. Ensure the server’s clock is accurately synchronized (use `ntp` or `chrony`). Significant time drift can cause P2P issues.

* **Issue**: Syncing is extremely slow.
  * **Check**: Hardware specifications. Are you meeting the recommended specs (especially RAM and **NVMe SSD**) outlined in the [Node Performance](/base-chain/node-operators/performance-tuning) guide? Disk I/O is often the bottleneck.
  * **Check**: L1 node performance. Is your L1 RPC endpoint responsive? A slow L1 node will slow down L2 sync.
  * **Check**: Network connection quality and bandwidth.
  * **Check**: `base-consensus` and execution client logs for any performance warnings or errors.

* **Issue**: `optimism_syncStatus` (port `7545` on `base-consensus`) shows a large time difference or errors.
  * **Action**: Check the logs for both the rollup node and the L2 execution client around the time the status was checked to identify the root cause (e.g., L1 connection issues, L2 client issues).

* **Issue**: `Error: nonce has already been used` when trying to send transactions.
  * **Cause**: The node is not yet fully synced to the head of the chain.
  * **Action**: Wait for the node to fully sync. Monitor progress using `optimism_syncStatus` or logs.

### Performance Issues

* **Issue**: High CPU, RAM, or Disk I/O usage.
  * **Check**: Hardware specifications against recommendations in the [Node Performance](/base-chain/node-operators/performance-tuning). Upgrade if necessary. Local NVMe SSDs are critical.
  * **Check**: Review client logs for specific errors or bottlenecks.

### Snapshot Restoration Problems

Refer to the [Snapshots](/base-chain/node-operators/snapshots) guide for the correct procedure.

* **Issue**: `wget` command fails or snapshot download is corrupted.
  * **Check**: Network connectivity.
  * **Check**: Available disk space.
  * **Action**: Retry the download. Verify the download URL is correct.

* **Issue**: `tar` extraction fails.
  * **Check**: Downloaded file integrity (is it corrupted?).
  * **Check**: Available disk space (extraction requires much more space than the download).
  * **Check**: `tar` command syntax.

* **Issue**: Node fails to start after restoring snapshot; logs show database errors or missing files.
  * **Check**: Did you stop the node (`docker compose down`) *before* modifying the data directory?
  * **Check**: Did you remove the *contents* of the old data directory (`./reth-data/*`) before extracting/moving the snapshot data?
  * **Check**: Was the snapshot data moved correctly? The chain data needs to be directly inside `./reth-data`, not in a nested subfolder (e.g., `./reth-data/reth/...`). Verify the folder structure.

* **Issue**: Ran out of disk space during download or extraction.
  * **Action**: Free up disk space or provision a larger volume. Remember the storage formula:
    ```
    (2 * chain_size + snapshot_size + 20% buffer)  
    ```

### Networking / Connectivity Issues

* **Issue**: RPC/WS connection refused (e.g., `curl` to `localhost:8545` fails).
  * **Check**: Is the L2 client container running (`docker compose ps`)?
  * **Check**: Are you using the correct port (`8545` for HTTP, `8546` for WS by default)?
  * **Check**: L2 client logs. Did it fail to start the RPC server?
  * **Check**: Are the `--http.addr` and `--ws.addr` flags set to `0.0.0.0` in the client config/entrypoint to allow external connections (within the Docker network)?

* **Issue**: Node has low peer count or cannot connect to any peers.
  * **Check**: Ingress ports `30303` (TCP/UDP) and `9222` (TCP/UDP for Reth discv5) are open on your firewall.
  * **Check**: Egress ports `30301` (TCP/UDP) and `9200` (UDP) are open for outbound traffic. These are required to reach Base bootnodes — if outbound connections to these ports are blocked, your node cannot initiate peer discovery and will find zero peers regardless of ingress rules.
  * **Check**: Node logs for P2P errors.
  * **Action**: If behind NAT, configure the `--nat=extip:<your-ip>` flag via `ADDITIONAL_ARGS` in the `.env` file (see [Networking](/base-chain/node-operators/run-a-base-node#networking)).

* **Issue**: Port conflicts reported in logs or `docker compose up` fails.
  * **Check**: Are other services running on the host using the default ports (`8545`, `8546`, `8551`, `6060`, `7545`, `30303`)? Use
    ```bash theme={null}
    sudo lsof -i -P -n | grep LISTEN
    sudo netstat -tulpn | grep LISTEN
    ```
  * **Action**: Stop the conflicting service or change the ports used by the Base node containers by modifying the `ports` section in `docker-compose.yml` and updating the relevant environment variables (`$RPC_PORT`, `$WS_PORT`, etc.) in the `.env` file if necessary.

***

## Getting Further Help

If you’ve followed this guide and are still encountering issues, seek help from the community:

* **Discord**: Join the [Base Discord](https://discord.gg/buildonbase) and post in the `🛠｜node-operators` channel, providing details about your setup, the issue, and relevant logs.
* **GitHub**: Check the [Base Node repository issues](https://github.com/base/node/issues) or open a new one if you suspect a bug.