hashicorp/nomad · error

Raft error when restoring snapshot: %v

Error message

Raft error when restoring snapshot: %v

What it means

After preparing the temp file, Restore() hands the snapshot to the Raft store via r.Restore(&metadata, snap, 0). This error wraps any failure reported by the Raft layer while installing the snapshot — the snapshot metadata or contents were rejected by Raft.

Source

Thrown at helper/snapshot/snapshot.go:300

	if err := read(decomp, &metadata, snap); err != nil {
		return fmt.Errorf("failed to read snapshot file: %v", err)
	}

	if err := concludeGzipRead(decomp); err != nil {
		return err
	}

	// Sync and rewind the file so it's ready to be read again.
	if err := snap.Sync(); err != nil {
		return fmt.Errorf("failed to sync temp snapshot: %v", err)
	}
	if _, err := snap.Seek(0, 0); err != nil {
		return fmt.Errorf("failed to rewind temp snapshot: %v", err)
	}

	// Feed the snapshot into Raft.
	if err := r.Restore(&metadata, snap, 0); err != nil {
		return fmt.Errorf("Raft error when restoring snapshot: %v", err)
	}

	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped %v cause from the Raft layer for the precise rejection reason.
2. Ensure the snapshot is not older than the Raft state it is applied to (restore to a node/state at or before the snapshot's index).
3. Verify producer/consumer library and snapshot-format versions are compatible.
4. Re-export a fresh snapshot from a healthy leader and retry; check Raft/FSM logs for underlying storage errors.

Example fix

// before
err := snapStore.Restore(staleSnapshotBytes) // Raft: snapshot is older than current state
// after
snap := exportFreshSnapshotFromLeader(cluster)
err := snapStore.Restore(snap)

meta, err := snapshotVerify(data) // parse header/metadata first
if err != nil { return err }
if raftStore.LastIndex() > meta.Index {
    return fmt.Errorf("snapshot index %d is behind raft state %d; refusing restore", meta.Index, raftStore.LastIndex())
}

if err := snapStore.Restore(data); err != nil {
    if strings.Contains(err.Error(), "Raft error when restoring snapshot") {
        // surface wrapped cause; compare snapshot index/term against cluster state
    }
}

When it happens

Trigger: The Raft implementation's Restore returns an error, e.g. snapshot metadata with an index/term older than existing state, unsupported snapshot version, failure while the FSM applies the restore, or I/O errors while Raft persists the snapshot.

Common situations: Restoring an outdated snapshot onto a cluster that has already applied newer entries; version mismatch between the snapshot producer and consumer; FSM restore callbacks failing (e.g. corrupted state store); Raft log/snapshot storage problems on disk.

Related errors

• unsupported minimum common raft protocol version
• No cluster leader
• Failed to create redacted snapshot: %v
• Raft error when taking snapshot: %v
• No servers found

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