hashicorp/terraform · error

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

Error message

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

What it means

From matchingChecksumAuthentication.AuthenticatePackage. The line for the filename was found and decoded cleanly, but the decoded SHA256 does not equal the WantSHA256Sum declared for the package. This cross-check guarantees the signed sums file authenticates the specific declared hash; a mismatch means the sums file and the package metadata disagree.

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 c9def3e214)

Solutions

1. Treat this as a registry/mirror consistency problem and report/follow the provider's published release; pin to a version where manifest and sums agree.
2. Clear any caches (local and proxy) that may serve a stale sums file or manifest, then re-init.
3. Use the official registry rather than a mirror until the inconsistency is resolved.
4. If you publish the provider, ensure the version manifest hash and the SHA256SUMS file are generated from the same artifact in the same release step.

Example fix

// before: manifest hash and signed sums disagree
// after: pin to a consistent release
required_version = ">= 5.2.0"  # version with consistent manifest+sums

// Cross-check the declared hash against the sums doc yourself first.
func declaredMatchesSums(doc []byte, filename string, want [sha256.Size]byte) bool {
    for _, line := range bytes.Split(doc, []byte("\n")) {
        p := bytes.Fields(line)
        if len(p) > 1 && bytes.Equal(p[1], []byte(filename)) {
            var got [sha256.Size]byte
            if _, err := hex.Decode(got[:], p[0]); err == nil { return bytes.Equal(got[:], want[:]) }
        }
    }
    return false
}

When it happens

Trigger: bytes.Equal(gotSHA256Sum[:], m.WantSHA256Sum[:]) is false at line 371. The SHA256SUMS lists one hash for the filename while the caller's WantSHA256Sum (typically from the registry version manifest) is different.

Common situations: A provider version was republished so the manifest's hash and the signed sums file are from different builds. A registry bug where the version manifest and SHA256SUMS are out of sync. A mirror assembled from mismatched artifacts. Replay/cache of an old sums file against a refreshed manifest.

Related errors

• checksum list has no SHA-256 hash for %q
• checksum list has invalid SHA256 hash %q: %s
• ErrChecksumDoesNotMatch
• failed to verify checksum of %s %s package cached in in %s:
• provider package doesn't match the expected checksum %q

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