hashicorp/nomad · error

failed to read snapshot: %w

Error message

failed to read snapshot: %w

What it means

`nomad operator snapshot inspect` copies the raft snapshot archive to a writer in a goroutine via snapshot.CopySnapshot. If reading/unarchiving the snapshot file fails (corrupt archive, truncated file, wrong file type), the error is wrapped with this message and sent to the caller.

Source

Thrown at command/operator_snapshot_inspect.go:186

	return 0
}

func inspect(file io.Reader) (*raft.SnapshotMeta, *SnapshotInfo, error) {
	info := &SnapshotInfo{
		Stats:     make(map[nomad.SnapshotType]typeStats),
		TotalSize: 0,
	}

	// w is closed by CopySnapshot
	r, w := io.Pipe()
	cr := &countingReader{wrappedReader: r}
	errCh := make(chan error)
	metaCh := make(chan *raft.SnapshotMeta)

	go func() {
		meta, err := snapshot.CopySnapshot(file, w)
		if err != nil {
			errCh <- fmt.Errorf("failed to read snapshot: %w", err)
		} else {
			metaCh <- meta
		}
	}()

	handler := func(header *nomad.SnapshotHeader, snapType nomad.SnapshotType, dec *codec.Decoder) error {
		name := snapType.String()
		stat := info.Stats[snapType]

		if stat.Name == "" {
			stat.Name = name
		}

		var val any
		err := dec.Decode(&val)
		if err != nil {
			return fmt.Errorf("failed to decode snapshot %q: %v", snapType, err)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Re-take the snapshot with `nomad operator snapshot save` and inspect the new file.
2. Verify the file is a genuine Nomad raft snapshot (check size/checksum vs the original, re-transfer if copied over the network).
3. Check the wrapped error (%w cause) for the underlying reason — e.g. bad archive header vs I/O error.
4. Confirm the Nomad version producing the snapshot matches the CLI version used to inspect it.

const stat = fs.statSync(snapshotPath); if (stat.size === 0 || stat.size < 512) throw new Error('file too small to be a raft snapshot'); const magic = fs.readFileSync(snapshotPath).slice(0, 4).toString(); if (magic.includes('PK') === false && magic.charCodeAt(0) === 0x1f) throw new Error('not a snapshot archive');

try { inspectSnapshot(file) } catch (e) { if (String(e).includes('failed to read snapshot')) { console.error('Snapshot file corrupt or not a raft snapshot; re-run: nomad operator snapshot save'); } throw e; }

When it happens

Trigger: Inspecting a snapshot file that is not a valid raft snapshot archive, is truncated/corrupted, or is unreadable at the byte level so CopySnapshot returns an error.

Common situations: Pointing the command at a different output file (e.g. a backup tarball or partial download), snapshots damaged during transfer from the server, or snapshots saved by an incompatible Nomad/raft version.

Related errors

• Failed to copy snapshot to temporary file: %v
• failed to open snapshot: %v:
• failed to reset heartbeat since server is not leader
• unsupported minimum common raft protocol version
• must provide peer id or address

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/cead2129653f1193. Report an issue: GitHub.