hashicorp/nomad · error

failed to read snapshot: %w

Error message

failed to read snapshot: %w

What it means

Inside RestoreFromArchive a goroutine runs snapshot.CopySnapshot(archive, w) to copy the snapshot archive into the pipe feeding the FSM restore. If CopySnapshot fails — the archive is not a valid Nomad snapshot, is truncated, or the pipe write fails because the FSM restore side closed early — the goroutine reports "failed to read snapshot: %w".

Source

Thrown at helper/raftutil/snapshot.go:36

func RestoreFromArchive(archive io.Reader, filter *nomad.FSMFilter) (raft.FSM, *state.StateStore, *raft.SnapshotMeta, error) {
	logger := hclog.L()

	fsm, err := dummyFSM(logger)
	if err != nil {
		return nil, nil, nil, fmt.Errorf("failed to create FSM: %w", err)
	}

	// r is closed by RestoreFiltered, w is closed by CopySnapshot
	r, w := io.Pipe()

	errCh := make(chan error)
	metaCh := make(chan *raft.SnapshotMeta)

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

	err = fsm.RestoreWithFilter(r, filter)
	if err != nil {
		return nil, nil, nil, fmt.Errorf("failed to restore from snapshot: %w", err)
	}

	select {
	case err := <-errCh:
		return nil, nil, nil, err
	case meta := <-metaCh:
		return fsm, fsm.State(), meta, nil
	}
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the archive is a complete, valid Nomad snapshot: check its size and, if possible, validate it (e.g. `nomad operator snapshot inspect <file>`).
2. Re-take or re-download the snapshot; a truncated transfer is the most common cause.
3. Check the wrapped error: if it is 'broken pipe' or 'io: read/write on closed pipe', the real failure is on the restore side (see the companion 'failed to restore from snapshot' error) — fix that cause.
4. Ensure the snapshot was produced by a compatible Nomad version; upgrade the tool if the snapshot is newer.

Example fix

// before: feeding a truncated file
f, _ := os.Open("snapshot.tar") // partially downloaded
fsm, _, _, err := raftutil.RestoreFromArchive(f, nil) // "failed to read snapshot: unexpected EOF"
// after: verify integrity first
if fi, _ := f.Stat(); fi.Size() == 0 { return fmt.Errorf("empty snapshot file") }
out, err := exec.Command("nomad", "operator", "snapshot", "inspect", path).CombinedOutput()
if err != nil { return fmt.Errorf("invalid snapshot: %s", out) }

// Validate the archive before feeding it to RestoreFromArchive
fi, err := os.Stat(path)
if err != nil || fi.Size() == 0 {
    return fmt.Errorf("snapshot file missing or empty")
}
if out, err := exec.Command("nomad", "operator", "snapshot", "inspect", path).CombinedOutput(); err != nil {
    return fmt.Errorf("invalid snapshot archive: %s", out)
}

fsm, store, meta, err := raftutil.RestoreFromArchive(archive, filter)
if err != nil {
    if strings.Contains(err.Error(), "failed to read snapshot") {
        if strings.Contains(err.Error(), "closed pipe") {
            return fmt.Errorf("restore side failed first; check 'failed to restore from snapshot' cause")
        }
        return fmt.Errorf("corrupt/truncated archive: %w", err)
    }
    return err
}

When it happens

Trigger: The io.Reader passed to RestoreFromArchive is not a valid snapshot archive (corrupt tar/gzip, wrong file, empty stream), or the FSM's RestoreWithFilter aborts and closes the read end of the pipe, causing CopySnapshot's write to fail with a broken pipe.

Common situations: Passing a truncated download or an unrelated file to the nomad-snapshot tool; a corrupted snapshot on disk; a snapshot from an incompatible Nomad version that fails mid-copy; the restore side erroring first so the copy side surfaces a broken-pipe error.

Related errors

• failed to read snapshot hashes: %v
• failed to decompress snapshot: %v
• failed to read snapshot file: %v
• failed to read snapshot: %w
• Failed to copy snapshot to temporary file: %v

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