| name | erigon-seg-integrity |
| description | Run integrity checks on Erigon datadirs using the 'erigon seg integrity' command. Use this when the user wants to verify snapshot/segment file integrity or during the snapshot publishing process. |
| allowed-tools | Bash, Read |
Erigon Segment Integrity Check
The erigon seg integrity command runs integrity checks on an Erigon datadir to verify that snapshot and segment files are valid and consistent.
Prerequisites
- Erigon must be stopped - The command requires exclusive access to the datadir
- Binary must be built - Run
/erigon-build first if the binary doesn't exist
- Datadir must exist - A synced Erigon datadir with blockchain data
Command Syntax
./build/bin/erigon seg integrity --datadir=<path>
Replace <path> with the actual path to your Erigon data directory.
Available Flags
--check — Comma-separated list of specific checks to run (default: all default checks)--skip-check — Comma-separated list of checks to exclude from the run--failFast — Stop after the first problem is found (default: true). Set to false to continue and collect all warnings--file-integrity-cache — Path to a cache file that speeds up repeated runs. Setting it also enables a torrent piece-hash verification pass before the checks--skip-check TorrentPieces — Skip that torrent verification pass; it is a named check like any other
Discovering Available Checks
The list of available checks is dynamic and changes over time as new checks are added or removed. Do NOT assume a fixed list. Instead, discover the current checks by running:
./build/bin/erigon seg integrity --help
Look at the --check flag description in the output — it lists all currently available check names.
Workflow
When the user wants to run integrity checks:
- Ask for the datadir path if not already provided
- Verify prerequisites
- Check the datadir exists
- Ensure Erigon is not running (file lock will prevent concurrent access)
- Build the binary if needed
- Discover available checks by running
--help if the user wants to run or skip specific checks
- Execute the command with the appropriate flags
- Interpret the output — report any errors or warnings found
Examples
Run all default checks
./build/bin/erigon seg integrity --datadir=/data/erigon
Run a specific check only
First discover available checks via --help, then:
./build/bin/erigon seg integrity --datadir=/data/erigon --check=<check_name>
Skip a specific check
./build/bin/erigon seg integrity --datadir=/data/erigon --skip-check=<check_name>
Continue past failures instead of stopping
./build/bin/erigon seg integrity --datadir=/data/erigon --failFast=false
Important Notes
- File Lock: If Erigon is running, the command will fail due to file lock
- Long running: Integrity checks can take significant time on large datadirs, especially mainnet
- Torrent verification scope: With
--file-integrity-cache set, the pre-pass scans <datadir>/snapshots recursively — top-level block segments plus caplin/, domain/, history/, idx/, accessor/. On a mainnet archive datadir that is roughly 2.6x the files of the top-level set; use --skip-check TorrentPieces to skip it
- Torrent verification exit code:
--failFast=false only means "verify every file before giving up" — a piece-hash mismatch, a path under snapshots/ the scan could not read, or an interrupted run all still exit non-zero. A partial or failed scan is never reported as a pass
- Discover checks dynamically: Always use
--help to find the current list of available checks rather than assuming fixed names
