hashicorp/nomad · error

failed to encode snapshot metadata: %v

Error message

failed to encode snapshot metadata: %v

What it means

write() encodes the snapshot metadata struct as JSON into meta.json before adding it to the tar archive. This error wraps the json.Encoder failure. It is rare because the metadata is a plain in-memory struct.

Source

Thrown at helper/snapshot/archive.go:116

// write takes a writer and creates an archive with the snapshot metadata,
// the snapshot itself, and adds some integrity checking information.
func write(out io.Writer, metadata *raft.SnapshotMeta, snap io.Reader) error {
	// Start a new tarball.
	now := time.Now()
	archive := tar.NewWriter(out)

	// 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,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the metadata struct contains only JSON-serializable types
2. Fix the underlying buffer/writer error reported in the wrapped %v
3. Pin or update the library version to one compatible with your metadata shape

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

When it happens

Trigger: enc.Encode(metadata) fails, typically from an unsupported type in the metadata struct (e.g. a channel or func field added by a version change) or an already-consumed/broken buffer writer.

Common situations: Upgrading the library and adding a non-serializable field to SnapshotMetadata, or memory/buffer issues.

Related errors

• error marshaling volume pramaters: %w
• failed to marshal json from Topic: %s, Type: %s, Err: %w
• could not serialize our own error: %v
• [✘] Role could not be interpolated with args: %w
• auth method could not be interpolated with args: %w

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