What causes "failed to write snapshot hashes header: %v" in hashicorp/nomad?

Free destination disk space before writing snapshots

failed to write snapshot hashes header: %v

Error message

failed to write snapshot hashes header: %v

What it means

write() adds the SHA256SUMS tar header sized to the encoded hash listing. This error wraps a failure writing that header to the archive sink. It indicates the destination writer failed while emitting the final entry's header.

Source

Thrown at helper/snapshot/archive.go:155

	}); err != nil {
		return fmt.Errorf("failed to write snapshot data header: %v", err)
	}
	if _, err := io.CopyN(archive, io.TeeReader(snap, snapHash), metadata.Size); err != nil {
		return fmt.Errorf("failed to write snapshot metadata: %v", err)
	}

	// Create a SHA256SUMS file that we can use to verify on restore.
	var shaBuffer bytes.Buffer
	if err := hl.Encode(&shaBuffer); err != nil {
		return fmt.Errorf("failed to encode snapshot hashes: %v", err)
	}
	if err := archive.WriteHeader(&tar.Header{
		Name:    "SHA256SUMS",
		Mode:    0600,
		Size:    int64(shaBuffer.Len()),
		ModTime: now,
	}); err != nil {
		return fmt.Errorf("failed to write snapshot hashes header: %v", err)
	}
	if _, err := io.Copy(archive, &shaBuffer); err != nil {
		return fmt.Errorf("failed to write snapshot metadata: %v", err)
	}

	// Finalize the archive.
	if err := archive.Close(); err != nil {
		return fmt.Errorf("failed to finalize snapshot: %v", err)
	}

	return nil
}

// read takes a reader and extracts the snapshot metadata and the snapshot
// itself, and also checks the integrity of the data. You must arrange to call
// Close() on the returned object or else you will leak a temporary file.
func read(in io.Reader, metadata *raft.SnapshotMeta, snap io.Writer) error {
	// Start a new tar reader.

View on GitHub (pinned to 482b49bf1a)

Solutions

Free destination disk space before writing snapshots
Verify the sink writer stays open through archive.Close()
Inspect the wrapped error for the concrete cause

Defensive patterns

Strategy: try-catch

Validate before calling

free, _ := diskFree(destPath)
if free < estimatedSnapshotSize+4096 {
    return errors.New("insufficient space")
}

Try / catch

if err := write(archive, metadata, snap); err != nil {
    if strings.Contains(err.Error(), "failed to write snapshot hashes header") {
        return fmt.Errorf("archive sink failed: %w", err)
    }
    return err
}

Prevention

Reserve space for all four entries (meta.json, state.bin, SHA256SUMS, padding)
Hold the sink open for the whole write
Check archive.Close() errors too

When it happens

Trigger: archive.WriteHeader for SHA256SUMS fails because the underlying writer errors: disk full, closed writer, or broken network stream.

Common situations: Destination storage exhausted near the end of a large snapshot; sink connection dropped.

Related errors

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