hashicorp/terraform · error

checksum list has unexpected SHA-256 hash

Error message

checksum list has unexpected SHA-256 hash %x (expected %x)

What it means

Thrown by matchingChecksumAuthentication.AuthenticatePackage when the line for m.Filename is found and decodes to a valid 32-byte SHA-256, but that hash does not equal m.WantSHA256Sum. This is a positive mismatch: the signed sums document asserts a hash that differs from what the caller expected for the package. Checked at package_authentication.go:370-372.

Solutions

1. Re-fetch both the package metadata and the signed sums document from the origin registry so they are from the same release state.
2. Confirm wantSHA256Sum passed to NewMatchingChecksumAuthentication comes from the same source/version as the sums document.
3. If both originate from the same registry and still disagree, report it as a registry inconsistency — do not weaken verification.
4. Clear any intermediary caches (mirror, CDN, CI cache) that could serve stale metadata or sums.

result, err := auth.AuthenticatePackage(loc)
if err != nil && strings.Contains(err.Error(), "checksum list has unexpected SHA-256 hash") {
    // metadata hash and signed sums disagree: re-fetch both from origin
    return result, err
}

When it happens

Trigger: NewMatchingChecksumAuthentication where wantSHA256Sum was computed/declared for different bytes than the registry's signed sums document lists. E.g. the package metadata's declared SHA-256 and the signed sums document disagree about the same filename.

Common situations: Provider repacked after the metadata hash was computed; mismatch between the package-metadata declared hash and the registry sums document (registry bug or stale cache); a mirror with an inconsistent sums document vs. metadata; tampering where one of the two values was altered.

Related errors

• checksum list has invalid SHA256 hash
• checksum list has no SHA-256 hash for
• archive has incorrect checksum
• provider package doesn't match the any of the expected…
• provider package doesn't match the expected checksum

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/14953cc4a18158fc. Report an issue: GitHub.

Appendix: source

Thrown at internal/getproviders/package_authentication.go:372

		parts := bytes.Fields(line)
		if len(parts) > 1 && bytes.Equal(parts[1], filename) {
			checksum = parts[0]
			break
		}
	}
	if checksum == nil {
		return nil, fmt.Errorf("checksum list has no SHA-256 hash for %q", m.Filename)
	}

	// Decode the ASCII checksum into a byte array for comparison.
	var gotSHA256Sum [sha256.Size]byte
	if _, err := hex.Decode(gotSHA256Sum[:], checksum); err != nil {
		return nil, fmt.Errorf("checksum list has invalid SHA256 hash %q: %s", string(checksum), err)
	}

	// If the checksums don't match, authentication fails.
	if !bytes.Equal(gotSHA256Sum[:], m.WantSHA256Sum[:]) {
		return nil, fmt.Errorf("checksum list has unexpected SHA-256 hash %x (expected %x)", gotSHA256Sum, m.WantSHA256Sum[:])
	}

	// Success! But this doesn't result in any real authentication, only a
	// lack of authentication errors, so we return a nil result.
	return nil, nil
}

type signatureAuthentication struct {
	Document  []byte
	Signature []byte
	Keys      []SigningKey
}

// NewSignatureAuthentication returns a PackageAuthentication implementation
// that verifies the cryptographic signature for a package against any of the
// provided keys.
//
// The signing key for a package will be auto detected by attempting each key

View on GitHub (pinned to d32a084675)