hashicorp/nomad · error

failed to write snapshot data header: %v

Error message

failed to write snapshot data header: %v

What it means

write() writes the state.bin tar header sized from metadata.Size before copying the snapshot data. This error wraps a failure writing that header. It means the archive sink rejected the header write for the snapshot data entry.

Source

Thrown at helper/snapshot/archive.go:138

		Mode:    0600,
		Size:    int64(metaBuffer.Len()),
		ModTime: now,
	}); err != nil {
		return fmt.Errorf("failed to write snapshot metadata header: %v", err)
	}
	if _, err := io.Copy(archive, io.TeeReader(&metaBuffer, metaHash)); err != nil {
		return fmt.Errorf("failed to write snapshot metadata: %v", err)
	}

	// Copy the snapshot data given the size from the metadata.
	snapHash := hl.Add("state.bin")
	if err := archive.WriteHeader(&tar.Header{
		Name:    "state.bin",
		Mode:    0600,
		Size:    metadata.Size,
		ModTime: now,
	}); 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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Validate metadata.Size is a correct non-negative value matching the snapshot data length
2. Check destination disk space and writer health
3. Inspect the wrapped error for the root cause

Example fix

// before
if err := archive.WriteHeader(&tar.Header{Name: "state.bin", Size: metadata.Size, ...}); err != nil { ... }
// after
if metadata.Size < 0 {
    return fmt.Errorf("invalid snapshot size: %d", metadata.Size)
}
if err := archive.WriteHeader(&tar.Header{Name: "state.bin", Size: metadata.Size, ...}); err != nil { ... }

if metadata.Size < 0 {
    return fmt.Errorf("invalid snapshot size %d", metadata.Size)
}

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

When it happens

Trigger: archive.WriteHeader for state.bin fails: underlying writer error (disk full, closed writer, broken pipe) or invalid metadata.Size (negative size header).

Common situations: metadata.Size corrupted or negative due to a bad metadata source; destination storage failure mid-snapshot.

Related errors

• failed to write snapshot metadata header: %v
• failed to write snapshot metadata: %v
• failed to write snapshot hashes header: %v
• failed to finalize snapshot: %v
• error reading snapshot: %w

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