This guide covers common issues encountered when setting up and running a Base node using the official Base Node Docker setup and provides steps to diagnose and resolve them.
Before diving into specific issues, here are some general steps that often help:
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.
docker compose logs -f op-geth
docker compose logs -f op-reth
docker compose logs -f op-node
. Look for errors, warnings, or repeated messages.Check Container Status: Ensure the relevant Docker containers are running: docker compose ps
. If a container is restarting frequently or exited, check its logs.
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.
Verify RPC Endpoints: Use curl
to check if the L2 client’s RPC endpoint is responding (see Running a Base Node > Verify Node is Running). Also, verify your L1 endpoints are correct and accessible from the node server.
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.
Issue: Docker command fails (docker compose up ...
)
node
directory containing docker-compose.yml
)?NETWORK_ENV
or CLIENT
).Issue: Container fails to start, logs show errors related to .env
files or environment variables.
OP_NODE_L1_ETH_RPC
, OP_NODE_L1_BEACON
) in the correct .env
file (.env.mainnet
or .env.sepolia
)?OP_NODE_L1_BEACON_ARCHIVER
endpoint set if required by your configuration or L1 node?OP_NODE_L1_RPC_KIND
set correctly for your L1 provider?RETH_CHAIN
and RETH_SEQUENCER_HTTP
correctly set in the .env
file?Issue: Errors related to JWT secret or authentication between op-node
and L2 client.
OP_NODE_L2_ENGINE_AUTH
variable or the JWT file path ($OP_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 (./geth-data
, ./reth-data
).
docker compose
has write permissions to the directory where the node
repository was cloned. Docker needs to be able to write to ./geth-data
or ./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.Issue: Node doesn’t start syncing or appears stuck (block height not increasing).
op-node
logs. Look for errors connecting to L1 endpoints or the L2 client.op-geth
/op-reth
) logs. Look for errors connecting to op-node
via the Engine API (port 8551
) or P2P issues.ntp
or chrony
). Significant time drift can cause P2P issues.Issue: Syncing is extremely slow.
op-node
and L2 client logs for any performance warnings or errors.Issue: optimism_syncStatus
(port 7545
on op-node
) shows a large time difference or errors.
op-node
and the L2 client (op-geth
/op-reth
) 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.
optimism_syncStatus
or logs.Refer to the Snapshots guide for the correct procedure.
Issue: wget
command fails or snapshot download is corrupted.
Issue: tar
extraction fails.
tar
command syntax.Issue: Node fails to start after restoring snapshot; logs show database errors or missing files.
docker compose down
) before modifying the data directory?./geth-data/*
or ./reth-data/*
) before extracting/moving the snapshot data?./geth-data
or ./reth-data
, not in a nested subfolder (e.g., ./geth-data/geth/...
). Verify the folder structure.Issue: Ran out of disk space during download or extraction.
Issue: RPC/WS connection refused (e.g., curl
to localhost:8545
fails).
op-geth
/op-reth
) running (docker compose ps
)?8545
for HTTP, 8546
for WS by default)?--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.
30303
) accessibility. Is it blocked by a firewall on the host or network?--nat=extip:<your-ip>
flag via ADDITIONAL_ARGS
in the .env
file (see Advanced Configuration).Issue: Port conflicts reported in logs or docker compose up
fails.
8545
, 8546
, 8551
, 6060
, 7545
, 30303
)? Use
ports
section in docker-compose.yml
and updating the relevant environment variables ($RPC_PORT
, $WS_PORT
, etc.) in the .env
file if necessary.If you’ve followed this guide and are still encountering issues, seek help from the community:
🛠|node-operators
channel, providing details about your setup, the issue, and relevant logs.This guide covers common issues encountered when setting up and running a Base node using the official Base Node Docker setup and provides steps to diagnose and resolve them.
Before diving into specific issues, here are some general steps that often help:
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.
docker compose logs -f op-geth
docker compose logs -f op-reth
docker compose logs -f op-node
. Look for errors, warnings, or repeated messages.Check Container Status: Ensure the relevant Docker containers are running: docker compose ps
. If a container is restarting frequently or exited, check its logs.
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.
Verify RPC Endpoints: Use curl
to check if the L2 client’s RPC endpoint is responding (see Running a Base Node > Verify Node is Running). Also, verify your L1 endpoints are correct and accessible from the node server.
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.
Issue: Docker command fails (docker compose up ...
)
node
directory containing docker-compose.yml
)?NETWORK_ENV
or CLIENT
).Issue: Container fails to start, logs show errors related to .env
files or environment variables.
OP_NODE_L1_ETH_RPC
, OP_NODE_L1_BEACON
) in the correct .env
file (.env.mainnet
or .env.sepolia
)?OP_NODE_L1_BEACON_ARCHIVER
endpoint set if required by your configuration or L1 node?OP_NODE_L1_RPC_KIND
set correctly for your L1 provider?RETH_CHAIN
and RETH_SEQUENCER_HTTP
correctly set in the .env
file?Issue: Errors related to JWT secret or authentication between op-node
and L2 client.
OP_NODE_L2_ENGINE_AUTH
variable or the JWT file path ($OP_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 (./geth-data
, ./reth-data
).
docker compose
has write permissions to the directory where the node
repository was cloned. Docker needs to be able to write to ./geth-data
or ./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.Issue: Node doesn’t start syncing or appears stuck (block height not increasing).
op-node
logs. Look for errors connecting to L1 endpoints or the L2 client.op-geth
/op-reth
) logs. Look for errors connecting to op-node
via the Engine API (port 8551
) or P2P issues.ntp
or chrony
). Significant time drift can cause P2P issues.Issue: Syncing is extremely slow.
op-node
and L2 client logs for any performance warnings or errors.Issue: optimism_syncStatus
(port 7545
on op-node
) shows a large time difference or errors.
op-node
and the L2 client (op-geth
/op-reth
) 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.
optimism_syncStatus
or logs.Refer to the Snapshots guide for the correct procedure.
Issue: wget
command fails or snapshot download is corrupted.
Issue: tar
extraction fails.
tar
command syntax.Issue: Node fails to start after restoring snapshot; logs show database errors or missing files.
docker compose down
) before modifying the data directory?./geth-data/*
or ./reth-data/*
) before extracting/moving the snapshot data?./geth-data
or ./reth-data
, not in a nested subfolder (e.g., ./geth-data/geth/...
). Verify the folder structure.Issue: Ran out of disk space during download or extraction.
Issue: RPC/WS connection refused (e.g., curl
to localhost:8545
fails).
op-geth
/op-reth
) running (docker compose ps
)?8545
for HTTP, 8546
for WS by default)?--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.
30303
) accessibility. Is it blocked by a firewall on the host or network?--nat=extip:<your-ip>
flag via ADDITIONAL_ARGS
in the .env
file (see Advanced Configuration).Issue: Port conflicts reported in logs or docker compose up
fails.
8545
, 8546
, 8551
, 6060
, 7545
, 30303
)? Use
ports
section in docker-compose.yml
and updating the relevant environment variables ($RPC_PORT
, $WS_PORT
, etc.) in the .env
file if necessary.If you’ve followed this guide and are still encountering issues, seek help from the community:
🛠|node-operators
channel, providing details about your setup, the issue, and relevant logs.