hashicorp/nomad · error

failed to rewind temp snapshot: %v

Error message

failed to rewind temp snapshot: %v

What it means

Restore() rewinds the temp snapshot file with snap.Seek(0, 0) so Raft can read it from the beginning. This error wraps a seek failure. It is very rare and indicates the file descriptor is no longer usable for seeking (invalid or errored file).

Source

Thrown at helper/snapshot/snapshot.go:295

		}
	}()

	// Read the archive.
	var metadata raft.SnapshotMeta
	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. Check the wrapped %v cause for EBADF/EMFILE/EIO and correlate with system logs.
2. Verify no other code closed the temp file descriptor before this point.
3. Check the process's open-file limit (ulimit -n) if EMFILE is reported.
4. Retry the restore after fixing the underlying filesystem/descriptor issue.

if err := snapStore.Restore(data); err != nil && strings.Contains(err.Error(), "failed to rewind temp snapshot") {
    // log the wrapped cause; check fd limits and filesystem health, then retry
}

When it happens

Trigger: snap.Seek(0, 0) returns an error during Restore — practically only when the file descriptor is invalid/closed or an underlying I/O error occurs on the device (e.g. EBADF, EIO).

Common situations: Filesystem/driver errors on the temp storage; extremely unusual conditions like the file being closed early due to a prior defer or descriptor exhaustion (EMFILE).

Related errors

• can't seek to offset %d: %w
• failed to rewind snapshot: %v
• unable to read rooted allocation directory
• Couldn't copy %q to %q: %w
• error writing to file %q: %w

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