hashicorp/terraform · error

checksum list has invalid SHA256 hash %q: %s

Error message

checksum list has invalid SHA256 hash %q: %s

What it means

From matchingChecksumAuthentication.AuthenticatePackage. A matching line was found, but hex.Decode failed turning the first field into a 32-byte SHA256. The '%q' is the offending token and '%s' the hex decoder's error. The sums file is malformed: the checksum field is not valid lowercase/uppercase hex of the right length.

Source

Thrown at internal/getproviders/package_authentication.go:367

	// Find the checksum in the list with matching filename. The document is
	// in the form "0123456789abcdef filename.zip".
	filename := []byte(m.Filename)
	var checksum []byte
	for _, line := range bytes.Split(m.Document, []byte("\n")) {
		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
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Fetch the SHA256SUMS document directly from the authoritative registry and confirm it is well-formed 64-hex-digit lines.
2. Fix or replace the mirror that is serving a malformed sums file.
3. Verify no proxy is altering response bodies (gzip/HTML-escape/charset rewriting).
4. If you generated the document yourself, emit standard '<64 lowercase hex> <filename>' lines.

Example fix

// before: sums file has a bad token
ABCD....  terraform-provider-aws_5.0.0_linux_amd64.zip   // not 64 hex
// after: well-formed line
9c7f...64hex...  terraform-provider-aws_5.0.0_linux_amd64.zip

// Reject malformed sums lines before handing them to the authenticator.
func validSums(doc []byte) error {
    for i, line := range bytes.Split(doc, []byte("\n")) {
        if len(bytes.TrimSpace(line)) == 0 { continue }
        p := bytes.Fields(line)
        if len(p) < 2 || len(p[0]) != 64 { return fmt.Errorf("line %d: malformed", i+1) }
        if _, err := hex.DecodeString(string(p[0])); err != nil { return err }
    }
    return nil
}

When it happens

Trigger: Line 353 found a row where parts[1]==filename, but parts[0] is not 64 valid hex characters; hex.Decode at line 366 returns an error (e.g. odd length, non-hex char, wrong byte count).

Common situations: A corrupted or hand-edited SHA256SUMS file. A mirror that re-encoded the file (uppercase, whitespace, line-ending changes producing stray characters). A registry/proxy that mangled the sums (truncation, HTML escaping turning a digit into an entity). A sums file using a different hash that happens to share the filename.

Related errors

• checksum list has no SHA-256 hash for %q
• checksum list has unexpected SHA-256 hash %x (expected %x)
• can't use local directory %q as a module registry address
• Error parsing provider ID from Registry: %s
• registry response includes invalid SHA256 hash %q: %s

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