| name | fukuii-sync-troubleshooting |
| description | Diagnose and fix stalled, slow, or stuck blockchain synchronization on a Fukuii node — SNAP sync and full/regular sync alike — covering pivot stalls, account/storage-range progress, peer starvation, and performance tuning. Use when sync is "stuck", "not progressing", "too slow", block height isn't advancing, or after a restart that won't catch up. Diagnosis is read-only; tuning changes config (restart required) under the guarded-write protocol. |
Fukuii sync troubleshooting
Read ../CONVENTIONS.md first. Diagnosis is 🟢; config/tuning edits are 🔴
(require restart) — gate them.
When to use
eth_syncing shows no forward progress over several minutes.- SNAP sync stuck at the pivot, or account/storage ranges not completing.
- Sync is healthy but far slower than the hardware should allow.
Inputs to gather first
Network, RPC port, datadir, sync mode (SNAP vs full), hardware (cores, RAM, disk
type). See CONVENTIONS §1.
Procedure
-
Confirm it's actually stalled (🟢) — sample eth_blockNumber and
eth_syncing ~30s apart. Use mcp_sync_status for SNAP phase/pivot detail.
No movement at all → stall; slow movement → tuning problem.
-
Check peers first (🟢) — sync needs peers. net_peerCount < 5 means the
problem is peering, not sync → fukuii-peer-management. Verify peers actually
serve the protocol/snap capability.
-
Scan logs (🟢) — fukuii-log-triage for ERROR/timeout/AccountRange/
pivot/RocksDB lines around the stall window.
-
SNAP-specific — pivot moves as the chain advances; a stuck pivot or stalled
AccountRangeCoordinator is a known failure family. Check progress of account
vs storage ranges. If genuinely wedged, the documented recovery is a clean
restart (🔴 — stops the node) or, last resort, a fast-sync reset via
fukuii_resetFastSync / fukuii_restartFastSync (🔴 — discards progress).
-
Performance tuning (🔴 — edits fukuii.conf, needs restart) — match
concurrency to CPU before touching anything else:
| CPU | snap-sync.account-concurrency | snap-sync.storage-concurrency |
|---|
| 2 cores | 8 | 4 |
| 4 cores (default) | 16 | 8 |
| 8+ cores | 32 | 16 |
Also relevant: disk must be SSD/NVMe (HDD will starve SNAP), adequate RAM,
and network bandwidth. Apply one change at a time and re-measure.
Decision guide
| Symptom | Likely cause | Action |
|---|
| 0 peers / < 5 | peering | fukuii-peer-management |
| Pivot/account-range wedged, errors in log | SNAP stall | restart (🔴) per runbook; re-sync if persistent |
| Progressing but slow, HDD | I/O bound | move datadir to SSD/NVMe |
| Slow on capable HW, low concurrency | under-tuned | raise concurrency to CPU table (🔴 restart) |
Deep reference
docs/runbooks/snap-sync-user-guide.md, snap-sync-faq.md,
snap-sync-performance-tuning.mddocs/operations/monitoring-snap-sync.mddocs/runbooks/known-issues.md (known SNAP failure modes)
Output
CONVENTIONS §4 block. State the measured progress rate as evidence, list any
config change made (and that a restart is required), and the re-measure result.
