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

# 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

```bash Run doctor theme={null}
# 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
```

<Tip>
  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.
</Tip>

## Related

* [basectl overview](/base-chain/node-operators/basectl/overview)
* [Inspect blocks and sync](/base-chain/node-operators/basectl/block-and-sync)
* [Node troubleshooting](/base-chain/node-operators/troubleshooting)
* [Performance tuning](/base-chain/node-operators/performance-tuning)