What causes "registry response includes invalid SHA256 hash %q: %s" in hashicorp/terraform?

Ensure the registry emits shasum as a lowercase hex SHA-256 digest of exactly 64 chars.

hashicorp/terraform · error · ErrQueryFailed

registry response includes invalid SHA256 hash %q: %s

Error message

registry response includes invalid SHA256 hash %q: %s

What it means

PackageMeta checks that the shasum field is exactly 64 hex characters (sha256.Size*2). If the length differs, the value cannot be a SHA-256 digest and the package is rejected via errQueryFailed (ErrQueryFailed). Note the message echoes err which at this branch is whatever prior error lingered, but the real cause is the wrong length.

Source

Thrown at internal/getproviders/registry_client.go:308

	}

	ret := PackageMeta{
		Provider:         provider,
		Version:          version,
		ProtocolVersions: protoVersions,
		TargetPlatform: Platform{
			OS:   body.OS,
			Arch: body.Arch,
		},
		Filename: body.Filename,
		Location: PackageHTTPURL(downloadURL.String()),
		// "Authentication" is populated below
	}

	if len(body.SHA256Sum) != sha256.Size*2 { // *2 because it's hex-encoded
		return PackageMeta{}, c.errQueryFailed(
			provider,
			fmt.Errorf("registry response includes invalid SHA256 hash %q: %s", body.SHA256Sum, err),
		)
	}

	var checksum [sha256.Size]byte
	_, err = hex.Decode(checksum[:], []byte(body.SHA256Sum))
	if err != nil {
		return PackageMeta{}, c.errQueryFailed(
			provider,
			fmt.Errorf("registry response includes invalid SHA256 hash %q: %s", body.SHA256Sum, err),
		)
	}

	shasumsURL, err := url.Parse(body.SHA256SumsURL)
	if err != nil {
		return PackageMeta{}, fmt.Errorf("registry response includes invalid SHASUMS URL: %s", err)
	}
	shasumsURL = resp.Request.URL.ResolveReference(shasumsURL)
	if shasumsURL.Scheme != "http" && shasumsURL.Scheme != "https" {

View on GitHub (pinned to c9def3e214)

Solutions

Ensure the registry emits shasum as a lowercase hex SHA-256 digest of exactly 64 chars.
If the registry only has another hash, compute/store the SHA-256 of the archive.
Strip any leading filename or whitespace from the field.

Example fix

// before
{"shasum":""}
// after
{"shasum":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}

Defensive patterns

Strategy: try-catch

Type guard

func isRegistryShasumLengthErr(err error) bool {
    var qf getproviders.ErrQueryFailed
    if errors.As(err, &qf) {
        return strings.Contains(qf.Wrapped.Error(), "invalid SHA256 hash")
    }
    return false
}

Try / catch

meta, err := client.PackageMeta(ctx, provider, ver, plat)
if err != nil {
    var qf getproviders.ErrQueryFailed
    if errors.As(err, &qf) && strings.Contains(qf.Wrapped.Error(), "invalid SHA256 hash") {
        // registry shasum is malformed; surface to registry maintainer
    }
    return err
}

Prevention

Registries must emit shasum as a 64-char lowercase hex SHA-256 digest.
Automate digest computation at publish time rather than copying by hand.
Add a publish-time unit test asserting len(shasum)==64.

When it happens

Trigger: Registry response's shasum field is not 64 characters: a raw binary hash, a base64 digest, a truncated/extra-long string, or empty.

Common situations: Custom registry stored the digest in base64 instead of hex; registry emits sha1 (40 chars) or sha512 (128 chars); field accidentally includes a filename prefix like in a SHASUMS line; empty field when the registry lacks checksums.

Related errors

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