hashicorp/nomad · error

failed to write snapshot metadata: %v

Error message

failed to write snapshot metadata: %v

What it means

After writing the meta.json header, write() copies the JSON bytes into the tar via io.Copy with a TeeReader feeding the metadata hash. This error wraps a copy failure while writing meta.json contents. Note the message says 'metadata' and refers to the meta.json body, not its header.

Source

Thrown at helper/snapshot/archive.go:127

	// 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)
	}

	// Create a SHA256SUMS file that we can use to verify on restore.
	var shaBuffer bytes.Buffer

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Free disk space or redirect the snapshot to storage with capacity for meta.json plus metadata.Size bytes
2. Retry the snapshot write after confirming the destination is writable
3. Read the wrapped error for the concrete cause

free, _ := diskFree(destPath)
if free < metadata.Size+1<<20 {
    return errors.New("insufficient space for snapshot")
}

if err := write(archive, metadata, snap); err != nil {
    if strings.Contains(err.Error(), "failed to write snapshot metadata: ") && !errors.Is(err, io.EOF) {
        return fmt.Errorf("snapshot write failed: %w", err)
    }
    return err
}

When it happens

Trigger: io.Copy(archive, io.TeeReader(&metaBuffer, metaHash)) fails because the underlying writer errors mid-write: disk full, connection reset, or writer closed.

Common situations: Destination disk fills during snapshot creation; network sink drops mid-stream.

Related errors

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