Skip to content

Conversation

@jadonamite
Copy link

### Overview
This PR creates a new, extensive `TROUBLESHOOTING.md` guide for the repository.

Currently, the repository lacks a centralized resource for debugging common runtime errors. This leads to repetitive issues regarding syncing, hardware requirements, and Docker misconfigurations. This PR fills that gap with a structured guide covering the most frequent operator pain points.

###Motivation & Context
Node operators frequently encounter issues that are not bugs in the code, but environmental or configuration constraints.
* **Context Deadline:** Users confuse disk bottlenecks with network errors.
* **JWT Errors:** Docker volume mapping often leads to auth failures between `op-node` and execution clients.
* **L1 Connection:** Derivation failures due to poor L1 RPC quality.

Providing a centralized "Self-Help" document will reduce the support burden on maintainers and discord moderators.

###  Content Included
The new guide covers three main categories:
1.  **Syncing & Performance:**
    * Detailed breakdown of the "Context Deadline Exceeded" error (IOPS vs Latency).
    * Snap sync behaviors ("Healing").
2.  **Configuration & Connectivity:**
    * Engine API (JWT) troubleshooting.
    * L1 RPC requirements and common failures.
    * P2P discovery (ports/firewalls).
3.  **Docker & Operations:**
    * Permission denied errors on data volumes.

### Checklist
- [x] Created `TROUBLESHOOTING.md`
- [x] Covered hardware/IOPS requirements extensively.
- [x] Included specific log signatures for easy `Ctrl+F` searching.

Added a comprehensive troubleshooting guide for Base node issues, covering syncing, configuration, connectivity, and Docker permissions.
Create troubleshooting guide for Base node operations
@cb-heimdall
Copy link
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