Check node health with basectl doctor

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.

Beryl Upgrade

Introduction

Core Concepts

Node Operators

Network Reference

API Reference

Protocol Specifications

Security

Check node health with basectl doctor

What it checks

Flags

Examples

​What it checks

​Flags

​Examples

​Related

What it checks

Flags

Examples

Related