Skip to content

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

Open
Cloakie47 wants to merge 1 commit intobase:masterfrom
Cloakie47:patch-1
Open

docs: add Flashblocks troubleshooting section for common node operator issues#1267
Cloakie47 wants to merge 1 commit intobase:masterfrom
Cloakie47:patch-1

Conversation

@Cloakie47
Copy link
Copy Markdown

The current node troubleshooting page covers general setup, syncing, performance, and snapshot issues but has no coverage of Flashblocks-specific errors that node operators commonly hit.

What changed? Why?
Added a new Flashblocks Issues section covering four common errors that have no documentation currently:

  1. missing canonical header race condition error, very common after restart or snapshot restoration, operators need to know it's safe to ignore briefly and what causes it
  2. No pong response from upstream WebSocket timeout, the default 500ms acts as both ping interval and pong timeout which is too aggressive, increasing to 1000-1500ms resolves it
  3. Non-sequential/non-zero index Flashblock errors caused by upstream WebSocket instability, node recovers automatically but operators get alarmed seeing repeated ERRORs with no guidance
  4. Pruned snapshot missing transaction data operators downloading the pruned snapshot can hit this and have no idea why or what to do

All four of these are real issues that node operators have reported with no existing documentation to help them diagnose or resolve.

Notes to reviewers
Docs-only change, no code modified. All issues documented are based on real reported behavior from node operators.

How has it been tested?
All four issues have been reproduced and confirmed by multiple node operators. The workarounds documented have been verified to resolve the issues.

Added troubleshooting information for Flashblocks issues, including causes and actions for various error messages.
@cb-heimdall
Copy link
Copy Markdown
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 0
Sum 1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants