Skip to content

docs: add Flashblocks troubleshooting section for common node operator issues #1267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Cloakie47 wants to merge 1 commit into
base: master
Choose a base branch
from
+17 −0
Open

docs: add Flashblocks troubleshooting section for common node operator issues #1267

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/base-chain/node-operators/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,23 @@ Refer to the [Snapshots](/base-chain/node-operators/snapshots) guide for the cor
- **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.

---
### [​](#flashblocks-issues) Flashblocks Issues

* **Issue**: `ERROR could not process Flashblock error=missing canonical header for block`
+ **Cause**: A race condition between the DB committing the previous canonical block and the arrival of new flashblocks. This is most common right after node restart or snapshot restoration.
+ **Action**: This error can be safely ignored if it appears briefly after a restart, it should resolve within a few minutes once the node is fully synced. If it persists, consider adding a small delay in your flashblock processor or upgrading to the latest base-reth version which includes fixes for this race condition.

* **Issue**: `WARN No pong response from upstream, reconnecting backoff=Xs timeout_ms=500`
+ **Cause**: The upstream flashblocks WebSocket (`wss://mainnet.flashblocks.base.org/ws`) is not responding to pings within the configured timeout. The default `timeout_ms=500` acts as both the ping interval and the pong timeout, which can be too aggressive.
+ **Action**: Increase the ping timeout value in your configuration. A value of `1000-1500ms` has been reported to resolve this issue by giving the upstream more time to respond.

* **Issue**: `ERROR Received non-sequential Flashblock for current block` or `ERROR Received non-zero index Flashblock for new block`
+ **Cause**: Flashblock messages are being dropped or arriving out of order from the upstream WebSocket, causing the pending state to be zeroed out.
+ **Action**: This is typically caused by upstream WebSocket instability. The node will automatically recover. If it happens frequently, check your network connection to the upstream WebSocket endpoint.

* **Issue**: Pruned snapshot causes `failed to find the L2 Heads` error after download
+ **Cause**: The pruned snapshot may be missing transaction data for certain blocks, causing the node to fail finding L2 heads on startup.
+ **Action**: Try using the full archive snapshot instead. If disk space is a concern, re-downloading the pruned snapshot may help if the previous one was corrupted, but if the issue persists the snapshot itself may need to be regenerated by the Base team.

## Getting Further Help

Expand Down