hashicorp/nomad · error

failed to write snapshot metadata header: %v

Error message

failed to write snapshot metadata header: %v

What it means

write() adds the meta.json tar header before writing its bytes. This error wraps a failure writing that tar header to the underlying archive writer. It indicates the destination writer rejected the header write.

Source

Thrown at helper/snapshot/archive.go:124

	// Create a hash list that we will use to write a SHA256SUMS file into
	// the archive.
	hl := newHashList()

	// Encode the snapshot metadata, which we need to feed back during a
	// restore.
	metaHash := hl.Add("meta.json")
	var metaBuffer bytes.Buffer
	enc := json.NewEncoder(&metaBuffer)
	if err := enc.Encode(metadata); err != nil {
		return fmt.Errorf("failed to encode snapshot metadata: %v", err)
	}
	if err := archive.WriteHeader(&tar.Header{
		Name:    "meta.json",
		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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check and free disk space on the destination
2. Verify the destination writer is open and healthy for the duration of write()
3. Inspect the wrapped error (%v) for the root cause (e.g. 'no space left on device')

if fi, err := dest.Stat(); err == nil && fi.Size() >= totalExpectedSize {
    // destination has room
}

if err := write(archive, metadata, snap); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) || strings.Contains(err.Error(), "no space left") {
        return fmt.Errorf("destination write failed: %w", err)
    }
    return err
}

When it happens

Trigger: archive.WriteHeader fails because the underlying io.Writer returned an error: disk full, closed writer, broken pipe on a network sink, or an invalid header (negative size).

Common situations: Writing a snapshot to a full disk, to an already-closed file, or over a failed network stream.

Related errors

• failed to write snapshot metadata: %v
• failed to write snapshot data header: %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/ba5f4ababb00d87a. Report an issue: GitHub.