hashicorp/nomad · error

failed to decode snapshot %q: %v

Error message

failed to decode snapshot %q: %v

What it means

While streaming entries out of a snapshot archive, each decoded value is read with dec.Decode(&val). If the codec fails to decode an entry of the snapshot (unexpected data layout, truncated section, version mismatch), the inspect handler aborts with this error naming the snapshot type.

Source

Thrown at command/operator_snapshot_inspect.go:203

		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)
		}

		size := cr.read - info.TotalSize
		stat.Sum += size
		stat.Count++
		info.TotalSize = cr.read
		info.TotalCount++
		info.Stats[snapType] = stat

		return nil
	}

	err := nomad.ReadSnapshot(cr, handler)
	if err != nil {
		return nil, nil, err
	}

	select {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Upgrade the nomad CLI to match (or exceed) the server version that created the snapshot and re-inspect.
2. Re-take a fresh snapshot with `nomad operator snapshot save` and inspect that instead.
3. Check snapType in the message to identify which section failed and compare against the wrapped codec error.
4. Re-download the snapshot if it was transferred over an unreliable channel.

try { inspectSnapshot(file) } catch (e) { if (String(e).match(/failed to decode snapshot/)) { console.error('Snapshot entry unreadable; upgrade nomad CLI or retake the snapshot:', e.message); } else { throw e; } }

When it happens

Trigger: The snapshot archive contains an entry whose bytes cannot be decoded into the expected structure — typically a truncated or corrupted snapshot, or a snapshot written by a newer Nomad version with a format the decoding CLI doesn't understand.

Common situations: Inspecting snapshots created by a newer Nomad release, snapshots corrupted mid-transfer, or hand-modified snapshot archives.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• volume snapshot ID cannot be updated
• failed to decode task state from 'simple-all' entry: %v
• error making snapshot: %v
• failed to read snapshot: %w
• dispatch error: %v

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