hashicorp/nomad · error
failed to decode snapshot
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.
Solutions
- Upgrade the nomad CLI to match (or exceed) the server version that created the snapshot and re-inspect.
- Re-take a fresh snapshot with `nomad operator snapshot save` and inspect that instead.
- Check snapType in the message to identify which section failed and compare against the wrapped codec error.
- Re-download the snapshot if it was transferred over an unreliable channel.
Defensive patterns
Strategy: try-catch
Try / catch
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; } } Prevention
- Keep the nomad CLI at the same or newer version than the servers that produced the snapshot.
- Re-download snapshots that were transferred over unreliable links.
- Never hand-edit snapshot archives.
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
- controller create snapshot
- controller delete snapshot
- controller list snapshots
- could not create snapshot
- dispatch error
AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04).
Data as JSON: /api/errors/1beab625ec0039ea.
Report an issue: GitHub.
Appendix: 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)