Check node health with basectl doctor

Run read-only health checks across a Base node’s execution layer, consensus layer, and L1 with basectl doctor, and get pass, warn, and fail results with adjustable thresholds.

basectl doctor runs a set of read-only health checks against one node and prints a result for each. It never changes anything on the node. The command exits with an error (1) if any check fails, and exits 0 when checks only pass, warn, are skipped, or report information.

By default, doctor uses the rpc, l1_rpc, and consensus_node_rpc URLs from your selected config. Use --el-rpc and --cl-rpc to point it at a different node.

What it checks

• The network your config says you’re on versus the chain ID the node actually reports
• P2P endpoint details
• Bootnode configuration
• Whether the node’s advertised endpoint looks correct
• Whether the node is reachable from the outside (via the Base telemetry service)
• Execution-layer and consensus-layer peer counts
• How far the node’s head is behind the public endpoint
• How recent the safe head is
• Optional reth.toml header/body limits
• Whether a consensus-node RPC is configured
• Whether the L1 RPC is reachable

The external reachability check uses the network detected from your --el-rpc. It’s skipped if the network can’t be detected or isn’t supported.

Flags

Flag	Default	Description
--el-rpc <URL>	config rpc	Use a specific execution-layer RPC URL.
--cl-rpc <URL>	config consensus_node_rpc	Use a specific consensus-node RPC URL. If it’s missing here and in your config, the consensus-layer checks are skipped with a hint.
--reth-config <PATH>		Path to your local reth.toml. Without it, the reth limits check is skipped.
--peer-warn-threshold <COUNT>	5	Warn if the peer count drops below this number.
--head-lag-warn-blocks <BLOCKS>	10	Warn if the node’s head is more than this many blocks behind the public endpoint.
--head-lag-fail-blocks <BLOCKS>	20	Fail if the node’s head is more than this many blocks behind the public endpoint.
--safe-recency-warn-blocks <BLOCKS>	150	Warn if the safe head is more than this many blocks behind the unsafe head.
--safe-recency-fail-blocks <BLOCKS>	300	Fail if the safe head is more than this many blocks behind the unsafe head.
--json		Print a JSON report with inputs, summary, and checks instead of text.

Examples

Run doctor

# Run using the URLs from your config
basectl -c mainnet doctor

# Run against a specific node
basectl -c mainnet doctor --el-rpc https://your-el.example/ --cl-rpc https://your-cl.example/

# Include the external reachability check
basectl -c mainnet doctor --el-rpc https://your-el.example/

# Check reth limits and print JSON
basectl -c mainnet doctor \
  --el-rpc https://your-el.example/ \
  --cl-rpc https://your-cl.example/ \
  --reth-config /etc/reth/reth.toml \
  --json

Because doctor exits with an error when a check fails, you can use it in health checks and CI. Adjust the threshold flags to make the warnings and failures fit your alerting.

Related

• basectl overview
• Inspect blocks and sync
• Node troubleshooting
• Performance tuning