hashicorp/nomad · error

failed to encode snapshot hashes: %v

Error message

failed to encode snapshot hashes: %v

What it means

Fires while writing a Nomad snapshot archive: encoding the SHA256SUMS hash list (hl.Encode) into the tar failed, so the archive is left without integrity data and the snapshot stream errors out.

Source

Thrown at helper/snapshot/archive.go:147

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped error for the exact encoding cause
2. Ensure hashes were added via hl.Add with standard sha256 hashers
3. Avoid modifying hashList internals; regenerate the snapshot

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

When it happens

Trigger: hashList.Encode fails, e.g. the internal hash values cannot be marshaled (hex/JSON encoding error) or the target buffer writer errors.

Common situations: Custom/modified hash list code, or an in-memory buffer write failure (very rare).

Related errors

• Could not re-encode redacted key: %v
• volume snapshot ID cannot be updated
• missing VolumeID
• missing SnapshotID
• failed to snapshot %s: %w

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