Snapshots Management

Erigon stores the majority of its chain data in snapshot files (.seg segments and associated index files). These immutable, compressed files cover headers, bodies, transactions, and state history. Because snapshots can occupy hundreds of gigabytes, understanding what is on disk — and how much space each category consumes — is essential for capacity planning and node maintenance.

seg du — Disk Usage Report

The seg du subcommand scans the snapshot directory for a given --datadir and reports a breakdown of disk usage by category, the detected (and configured) node type, and estimated sizes for each pruning mode.

Syntax

erigon seg du [--datadir <path>] [--json] [-v | --verbose]

Flags

Flag	Description
--datadir <path>	Path to the Erigon data directory. Defaults to Erigon's standard data directory (paths.DefaultDataDir(), OS-specific) when omitted. seg du has no --chain flag, so this default is chain-agnostic.
--json	Output results as JSON instead of human-readable text. Useful for scripting or dashboards.
-v, --verbose	Show a per-domain / per-type subcategory breakdown within each category.

Example output (human-readable)

mainnet | archive | blocks 0–25.296.000 | steps 0–9.153
total: 1.8TB (4285 files)

── Breakdown ──────────────────────────────────────────────────
  block segments          900.2GB      48.3%   1195 files
  domains                 306.3GB      16.4%    154 files
  inverted indices        299.7GB      16.1%    596 files
  history                 230.7GB      12.4%    296 files
  accessors               127.7GB       6.8%    892 files
  other                     9.8MB       0.0%   1152 files
    extensions: .toml, .torrent, .txt

── Estimated Size by Node Type ────────────────────────────────
  archive            1.8TB          —    all blocks      all history
  full             361.2GB     -1.5TB    last 262.144    last 262.144
  blocks             1.2TB   -589.9GB    all blocks      last 262.144
  minimal          342.3GB     -1.5TB    last 100.000    last 100.000

Sizes use Erigon's ByteCount format (e.g. 850.4GB, 1.2TB — binary scale, no space). Block/step counts and prune-window sizes use . as the thousands separator, matching the binary's own output.

The estimator only sums files already on disk, so the archive row always equals the current total and no node-type estimate can exceed it. Estimates are therefore most meaningful against an archive datadir (shown above); on an already-pruned node the larger modes are capped at what is physically present. Rows are always printed in the fixed order archive → full → blocks → minimal.

Header fields explained:

• Chain — detected from chaindata (falls back to unknown if the database is locked or empty).
• Mode — the configured pruning mode read from the database, plus the mode detected from which files are present on disk. If they disagree, both are shown (e.g., full (files look like archive)).
• blocks 0–N — the highest block number across all block segment files.
• steps 0–N — the highest step number across all state files. A step is an internal Erigon unit covering a fixed number of transactions (config3.DefaultStepSize = 390,625 txNums), so the number of blocks per step varies with chain activity.

Breakdown categories:

The category labels below are exactly what the command prints.

Category	Contents
domains	Current-state domain files (latest accounts, storage, code, commitment). Never pruned, so typically the largest category on pruned (full / minimal) nodes; on an archive node, block segments dominate.
block segments	Headers, bodies, and transactions (.seg + index files) directly under snapshots/.
history	State-history snapshots for accounts, storage, code.
inverted indices	Inverted indices over state history (enables range lookups).
accessors	Accessor index files that speed up state queries.
caplin	Consensus-layer (beacon chain) snapshots.
commitment hist	Commitment-history files (archive nodes only).
rcache	Receipt cache (pre-computed receipts for RPC performance).
other	Any files with unrecognised extensions (listed inline).

Estimates table: shows how much space the current snapshot set would occupy under each pruning mode, given the files already on disk. The delta column is relative to archive (negative = smaller than archive). This lets you compare your current footprint against what other modes would consume without resyncing.

Example output (verbose, -v)

With --verbose, each category expands into its domain or type subcategories (excerpt — every category expands the same way):

  block segments          900.2GB      48.3%   1195 files
  ├─ transactions        874.2GB      97.1%    174 files
  ├─ txn2block            12.3GB       1.4%     87 files
  ├─ headers              10.3GB       1.1%    174 files
  ├─ bodies                3.3GB       0.4%    174 files
  └─ blocksidecars        26.9MB       0.0%    586 files

  domains                 306.3GB      16.4%    154 files
  ├─ commitment          195.0GB      63.7%     22 files
  ├─ storage              79.7GB      26.0%     33 files
  ├─ code                 16.5GB       5.4%     33 files
  ├─ accounts             15.1GB       4.9%     33 files
  └─ receipt               6.1KB       0.0%     33 files

JSON output (--json)

Use --json to get a machine-readable object suitable for scripting:

erigon seg du --datadir /data/erigon --json | jq '.estimates'

The JSON schema matches the duResult struct: top-level fields chain, configured_mode, detected_mode, block_range, step_range, total_bytes, total_files, categories, subcategories, other_extensions, estimates.

tip

Run seg du while the node is stopped. If Erigon is running and holds the database lock, the command falls back to unknown for the chain name and omits the configured mode — it will still scan snapshot files and produce size figures, but mode information will be incomplete.

---

Snapshot Types (Pruning Modes)

The snapshot set on disk reflects the node's pruning mode, and seg du automatically detects which mode your current files correspond to. For what each mode retains and how to choose one, see Pruning Modes.

The seg du estimates table shows the projected disk footprint for each mode given the files currently present, so you can evaluate a mode change before committing to a resync.

---

Commitment Snapshot Format (New in v3.6)

A commitment snapshot file stores Merkle-Patricia trie branches. Each branch has to refer to the account and storage keys underneath it, and Erigon can encode those references in one of two ways:

Encoding	What a branch stores	When a file uses it
Referenced	Shortened keys — offsets into the accounts and storage files, which must be dereferenced on read	Stamped below v2.2 and spanning at least 2 steps
Plain	The keys themselves, inline	v2.2 and later, or a sub-v2.2 file spanning fewer than 2 steps

The version stamp alone does not decide the encoding. CommitmentBranchReferenced (in db/state/domain_committed.go) requires both a version below v2.2 and a range of at least commitment.DefaultKeyReferencingMinSteps (2) steps, so a small v2.1 file — a single unmerged step — is plain despite its stamp.

Plain files are larger on disk, but state reads and snapshot merges are faster, because nothing has to be looked up in the accounts and storage files first.

v3.6 makes plain the default for newly written commitment files. In v3.5 and earlier the default was referenced.

The choice is recorded per datadir as references_in_commitment_branches in snapshots/erigondb.toml. When that file omits the field, the compiled default applies — false (plain) from v3.6, true (referenced) before it. On a normal fresh sync the downloader delivers erigondb.toml along with the snapshot set, so the published set decides the regime.

What happens to an existing datadir

Nothing breaks, and nothing is rewritten eagerly:

• Existing referenced files stay readable. Whether a commitment file carries shortened references is a property of that file — its version stamp and step range — not of the current setting. The commitment domain reads v2.1 and v2.2 alike.
• Conversion happens lazily, during merges — but only for files that merge again. When a merge has any referenced input, Erigon attaches a value transformer that expands the references; because new files are written plain, the merged output lands as v2.2. No operator action, no downtime.

Lazy conversion is not a guarantee that the datadir ends up fully plain. Two conditions have to hold, and neither is automatic:

• Plain writes must actually be selected for this datadir. The compiled default is plain from v3.6, but an explicit references_in_commitment_branches in snapshots/erigondb.toml overrides it, and while it reads true merges keep writing referenced output — nothing migrates, however long the node runs. A datadir carried over from v3.5 will not have the key: v3.5's erigondb.toml recorded only step_size and steps_in_frozen_file, and v3.6 and later never add the field to a file that already exists. A datadir from v3.3 or earlier (a preverified.toml but no erigondb.toml) is the exception: on its first start Erigon creates the file with the legacy step size and writes the field explicitly — plain, unless --commitment.plainValues=false is passed on that start. So for a plain v3.5 upgrade this condition holds by default; it is the one to check if the toml has been hand-edited, or if a published set delivered one that sets it.
• The file has to take part in a later merge. Under the default cap, merge spans stop at stepSize * steps_in_frozen_file (findMergeRange in db/state/aggregator.go), and a file that already covers the whole candidate range is skipped (findMergeRangeInFiles in db/state/merge.go). A commitment file already at the frozen span therefore has nothing left to merge into and stays referenced indefinitely. --erigondb.domain.steps-in-frozen-file raises that cap (or lifts it entirely), which lets frozen files merge again — but that is an explicit operator choice, not something an upgrade does.

So the two paths below are not simply a faster route to where merging would arrive anyway: short of raising the merge cap yourself, they are the only route for files that are already frozen. For most operators upgrading from v3.5 the correct action is still none — referenced files stay readable, and the encoding is a performance property, not a correctness one. Take a path below only if you want plain across the whole datadir, and are prepared to pay for it.

warning

Downgrading to v3.5 after v3.6 has written new snapshot files is not supported — the new snapshot and accessor formats are incompatible with v3.5. Back up your --datadir before taking either migration path below.

Path 1 — re-download the snapshot set (erigon seg reset)

Reconciles the local snapshot set against the published preverified set, then lets the next start fetch what is missing in the published v3.6 form, which is already plain. At the default --local=true it removes what the preverified set does not describe. Independently of --local, it also removes any file whose .torrent carries the wrong infohash or cannot be read at all, together with the data file that torrent vouched for. Everything else the set does describe stays.

erigon seg reset --datadir /your/datadir

Flag	Description
--datadir <path>	Path to the Erigon data directory.
--local, -l	A single switch over two behaviours: remove snapshot files that are not described in the preverified set (locally generated ones), and remove chaindata/ together with any heimdall/ and polygon-bridge/ directories left over from former Polygon support. Default: true. --local=false keeps all of them, subject to the mixed-build check below.
--allow-mixed-state	Proceed even when a step range would keep its commitment file and its accounts/storage files from different builds. Default: false.
--dry-run, -n	Print the files that would be removed and exit without removing anything. Default: false.
--preverified <remote|local>	Which preverified snapshot list to reset against. Default: remote.

seg reset is destructive and not reversible: at the default --local=true it deletes chaindata/, any leftover heimdall/ and polygon-bridge/ directories, and any locally generated snapshot files. Independently of --local — that is, even with --local=false — it also deletes any .torrent file whose infohash does not match the preverified list, together with the snapshot data file that torrent vouched for (a stale local build is unverifiable, so the downloader must re-fetch the canonical copy). All other preverified snapshots already on disk are kept and corrected by the downloader on the next start. The node must be stopped — the command takes an exclusive lock on the datadir.

At --local=false a locally built file can survive next to a canonical one. If that would leave a step range whose commitment file stores references from a different build than its accounts or storage file, seg reset refuses before removing anything and names the ranges: those references are byte offsets into the accounts and storage files of the same build. Remove the ranges with erigon seg rm-state-snapshots --datadir /your/datadir --step=<range>, or pass --allow-mixed-state to proceed anyway. At --local=true the check does not apply, since every locally built file is removed.

Cost: whatever the downloader has to re-fetch, plus rebuilding state on the next start. Run --dry-run first, and back up the datadir.

Size that cost by how far the node is past the published preverified manifest, not by download time. The manifest can lag the live tip considerably, and only the range it covers can be restored by fetching a torrent. Blocks past it are held either in chaindata/ or in locally built segments — and at --local=true seg reset removes both (the reset path in db/datadir/reset). That range then comes back through Caplin's per-block beacon backfill rather than a segment fetch, which is orders of magnitude slower, and a node far enough behind it may need more than one restart before execution resumes.

seg reset has no --chain flag of its own; it reads the chain name from chaindata/. If chaindata/ is missing or unreadable, pass --chain — it is a root-level flag and resolves in either position: erigon --chain mainnet seg reset --datadir /your/datadir and erigon seg reset --chain mainnet --datadir /your/datadir behave the same.

note

erigon seg reset is not new in v3.6 (seg is an alias for snapshots, so erigon snapshots reset is the same command). What is new is its role as a shortcut to the plain commitment format. See also Snapshots Upgrade Options.

Path 2 — offline conversion (integration commitment convert) (New in v3.6)

Re-encodes the commitment files already on disk instead of re-downloading them. Built from source as build/bin/integration (make integration).

integration commitment convert --datadir /your/datadir --chain mainnet

Both encoding flags default to false, and false is the target state that matches what v3.6 writes — so the command above, with no encoding flags, targets plain values and V1 keys. Conversion is driven by both axes at once, not only the value axis: a file that is already plain but carries V2 keys is still rewritten, because its key encoding does not match the target.

Flag	Description
--datadir <path>	Path to the Erigon data directory.
--chain <name>	Chain name.
--squeeze	Target state of the value axis: true = referenced (offsets), false = plain. Default: false.
--nibbles.v2	Target state of the key axis: true = V2, false = V1 (compact bytes, what Erigon writes). Default: false.
--restore	Move the originals back from snapshots/backup/domains/ and remove the converted files. Mutually exclusive with --squeeze / --nibbles.v2 and with --continue.
--continue	Resume an interrupted run, reusing complete shards left in snapshots/rebuild/domain/. Mutually exclusive with --restore.

The flag value is the target state, not a direction: the tool detects each file's current encoding and converts only what needs it. A file is skipped only when both axes already match the target — st.keysV2 == TargetNibblesV2 && st.squeezed == effectiveTargetSqueeze — so a mismatch on either axis rewrites the file.

Is it reversible? Yes — this is the one path with a real undo. The originals are moved to snapshots/backup/domains/, and --restore puts them back, removing from snapshots/domain/ the converted files that had already been moved in. Restore is filesystem-only and runs even when the datadir is too broken for Erigon to open it, and it tolerates a partially completed restore, so it can be re-run. It then tries to remove the backup directory itself, which is what unblocks the next conversion — but a failure there is only logged as a warning and restore still reports success, so confirm snapshots/backup/domains/ is actually gone — or at least empty, which is all pre-flight requires — before converting again. It does not touch snapshots/rebuild/domain/.

danger

A non-empty snapshots/backup/domains/ blocks the next conversion, and pre-flight's own error message suggests rm -rf-ing it. Do not. If the run stopped before the converted files were moved into snapshots/domain/, the originals exist nowhere but that backup, and a re-run without --continue can wipe snapshots/rebuild/domain/ on pre-flight — so clearing the backup and retrying can leave you with neither set. (If promotion had already finished, the converted files are live and only the originals go, which is survivable but still irreversible.) Empty it with --restore instead, but first copy snapshots/domain/, snapshots/backup/domains/ and snapshots/rebuild/domain/ aside (see If a run is interrupted below): restore can itself delete the only remaining copy of a step range. Delete the backup by hand only after a run has printed DONE and you have started the node on the converted datadir.

Does it stick? Only if this datadir is set to write plain. The command flips the referencing flag for the duration of the run and puts it back on exit; it never rewrites snapshots/erigondb.toml (an existing one is read verbatim and left alone). So on a datadir whose toml carries references_in_commitment_branches = true, the next Erigon start reads that true again and later merges re-shorten their output — you pay for the conversion and merging gradually undoes it. Check that field before converting.

Is the node stopped? It must be, but nothing enforces it. The command opens the chaindata DB read-write and applies migrations; it opens with Accede(true) and takes no datadir lock, and --restore runs before the DB opens at all.

What does it cost? Every commitment .kv file whose encoding does not already match the target on both axes is rewritten and its accessors (.kvi / .bt / .kvei) rebuilt — which includes a file that is already plain but carries V2 keys, since the default target is V1. Sizing this by the referenced files alone understates it. Converted output is written into snapshots/rebuild/domain/ while the originals are still in place, so at peak you need free space for a second copy of the commitment domain — use the commitment row of erigon seg du --datadir <path> -v to size it. Plain output is larger than the referenced input.

If a run is interrupted

What to do depends on how far it got, and snapshots/backup/domains/ is what tells you:

• Backup still empty — interrupted while converting. The originals are untouched in snapshots/domain/ and the partial output is in snapshots/rebuild/domain/. Resume with --continue, which keeps the shards that completed and redoes only the rest, or re-run without it to start over — pre-flight wipes snapshots/rebuild/domain/ only when --continue is absent. Nothing is at risk either way.

  --continue can refuse with a non-contiguous shards error even though nothing is wrong: it needs the finished shards to form an unbroken prefix of the input, and a file that was already at the target encoding produces no shard at all, which reads as a gap. Re-run without --continue when that happens. The originals have not moved yet, so the only cost is redoing the work.

• Backup non-empty — interrupted while moving the originals out or the converted files in. The two cases look different on disk: the converted files are moved in only after every original has been moved out, so if snapshots/domain/ still holds originals the run died while backing up, and if it holds converted files it died while promoting. Either way, take the copy described below, then run --restore and let it finish.

  A non-empty backup does not always mean the conversion failed — it is also what you see if the run finished the rewrite and then failed to reload the files. Restoring in that case undoes a conversion that had actually completed. It costs time, not data.

danger

Copy snapshots/domain/, snapshots/backup/domains/ and snapshots/rebuild/domain/ aside before you restore. Restore decides what to sweep out of snapshots/domain/ by comparing against the files it finds in the backup, and it cannot tell an original that had not been moved yet from a converted file that had already been moved in. If the run died midway through moving one step range's files out, restore deletes the part of that range still sitting in snapshots/domain/ — and reports success.

At that moment the only remaining copy of that range is the converted one in snapshots/rebuild/domain/, which a conversion re-run without --continue discards on pre-flight. So do not convert again straight after a restore: check first that every commitment step range present before the interrupted run is back in snapshots/domain/, and if one is short, recover it from your copy before running anything else.

warning

When you resume with --continue, you must pass the same --squeeze and --nibbles.v2 values as the original run. A mismatch silently produces mixed-encoding output.

Prerequisite for legacy step sizes (erigon seg step-rebase)

Erigon groups state files into steps. The step size is a per-datadir record in snapshots/erigondb.toml, taken from the published snapshot set, and the smaller 390,625-transaction step (a quarter of the old 1,562,500, giving about 4× smaller chaindata/) was offered rather than forced. A fresh sync has received 390,625 since v3.4; the compiled fallback, used only without the downloader, stayed at 1,562,500 through v3.4.4 and became 390,625 in v3.5. A datadir created by Erigon 3.3 or earlier stays at the legacy size until rebased. Do not infer the step size from the version — read the file. Since v3.6 the release notes require those datadirs to rebase, or to take the seg reset path above, before their first normal start on v3.6 or later.

Check step_size in snapshots/erigondb.toml. If it reads 1562500:

erigon seg step-rebase --datadir /your/datadir --new-step-size=390625

Flag	Description
--datadir <path>	Path to the Erigon data directory.
--new-step-size <n>	Required. Target step size. 390625 is the current default. Must be a whole multiple or a whole divisor of the datadir's present step size.
--keep-blocks	Keep chaindata/ and reset only the execution-state tables inside it, so already-downloaded blocks can be re-executed instead of re-downloaded. Default: delete chaindata/ entirely.

What it does: renames every state snapshot file under snapshots/domain, history, accessor, and idx so its step numbers are rescaled by the factor; deletes the .torrent files in those directories and snapshots/erigondb.toml.torrent, which the rebase invalidates; deletes chaindata/ (or, with --keep-blocks, resets its execution-state tables); and rewrites snapshots/erigondb.toml with the new step_size and a correspondingly rescaled steps_in_frozen_file. The rewritten file drops references_in_commitment_branches, so an explicit true becomes the default, plain, after the rebase. Increasing the step size divides file bounds without a divisibility check, so a range that is not a multiple of the factor is truncated (0-1 becomes 0-0 at factor 2).

The command prints the full rename and delete plan and asks for confirmation (Proceed with these changes? [y/N]) before touching anything, and exits as a no-op if the datadir is already at the requested step size. It is destructive and has no built-in undo, and an interrupted run must not simply be re-run: the new step size is written only after every rename has completed, so a crash partway through leaves the old size recorded next to partly renamed files. A second run reads that old size and rescales the already-renamed files again, corrupting their ranges. Recover the datadir from a backup instead. The node must be stopped — it locks the datadir (and, with --keep-blocks, additionally opens chaindata/ exclusively). The v3.4.0 release notes put the rebase itself at roughly ten seconds; the cost that follows is re-acquiring whatever was in chaindata/.

---

Upgrading Snapshots in v3.5

EIP-8252 retention window change

v3.5 retargets the Full and Blocks pruning modes to the EIP-8252 reorg-retention window (262,144 blocks, ~36 days), up from the previous 100,000-block window. This changes which snapshot files are present on disk after upgrading — most notably, full nodes prune older block segments down to the window, freeing space. Existing datadirs migrate automatically on first start.

Decide before that first start if you need to keep more than the window: pruning is not reversible, and block data already discarded comes back only by re-syncing. To retain every post-merge block under Full mode, pass --prune.distance.blocks=18446744073709551615 — v3.5 takes this option as a number; the readable keep-post-merge alias only exists from v3.6. --prune.mode=blocks keeps every block back to genesis. See Pruning Modes for what each mode keeps.

After the first prune pass, run seg du to inspect the resulting on-disk breakdown.

Manual snapshot operations

To migrate snapshots to the latest format, reset them for maximum performance after a major upgrade, or downgrade to an older snapshot format, follow the step-by-step snapshot upgrade and downgrade instructions in the Upgrading guide. Those commands are subcommands of erigon snapshots (e.g. erigon snapshots update-to-new-ver-format --datadir /your/datadir).

warning

Always back up your --datadir before running snapshot reset, upgrade, or downgrade commands.