hashicorp/nomad · error

hash check failed for %q

Error message

hash check failed for %q

What it means

DecodeAndVerify walks the SHA256SUMS listing inside a snapshot archive and compares each recorded hash against the hash of the data actually read from the archive. This error means the computed SHA256 of an entry does not match the hash listed in SHA256SUMS. The library throws it to guarantee snapshot integrity before a restore proceeds.

Source

Thrown at helper/snapshot/archive.go:81

// DecodeAndVerify reads a SHA256SUMS-style text file and checks the results
// against the current sums for all the hashes.
func (hl *hashList) DecodeAndVerify(r io.Reader) error {
	// Read the file and make sure everything in there has a matching hash.
	seen := make(map[string]struct{})
	s := bufio.NewScanner(r)
	for s.Scan() {
		sha := make([]byte, sha256.Size)
		var file string
		if _, err := fmt.Sscanf(s.Text(), "%x  %s", &sha, &file); err != nil {
			return err
		}

		h, ok := hl.hashes[file]
		if !ok {
			return fmt.Errorf("list missing hash for %q", file)
		}
		if !bytes.Equal(sha, h.Sum([]byte{})) {
			return fmt.Errorf("hash check failed for %q", file)
		}
		seen[file] = struct{}{}
	}
	if err := s.Err(); err != nil {
		return err
	}

	// Make sure everything we had a hash for was seen.
	for file := range hl.hashes {
		if _, ok := seen[file]; !ok {
			return fmt.Errorf("file missing for %q", file)
		}
	}

	return nil
}

// write takes a writer and creates an archive with the snapshot metadata,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Recreate the snapshot with write() instead of hand-editing the archive
2. Verify the transfer checksum of the whole snapshot file (e.g. compare sha256 of the file before/after copy)
3. Ensure tar entry Sizes exactly match content length (metadata.Size for state.bin)
4. Check storage/disk for corruption; re-copy from a trusted source

sum, err := os.ReadFile("SHA256SUMS")
fileSum, err := sha256sumFile(snapshotPath)
if err != nil || !bytes.Equal(sum, fileSum) {
    return errors.New("snapshot archive corrupted; re-transfer")
}

if err := snapshot.DecodeAndVerify(w, r, size); err != nil {
    if strings.Contains(err.Error(), "hash check failed") {
        // treat as corruption: discard and re-acquire snapshot
    }
    return err
}

When it happens

Trigger: The archive contents were modified/corrupted after writing, the writer mis-sized a tar entry (Size mismatch so bytes shift between entries), or a non-standard tool rewrote the tar changing byte order/content while keeping entries.

Common situations: Manual editing or repacking of a .snap archive, truncation from a failed upload/download, disk corruption, or writing state.bin with a size differing from metadata.Size.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• list missing hash for %q
• file missing for %q
• failed checking integrity of snapshot: %v
• volume snapshot ID cannot be updated
• missing VolumeID

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