hashicorp/terraform · error · ErrQueryFailed

failed to retrieve cryptographic signature for provider: %s

Error message

failed to retrieve cryptographic signature for provider: %s

What it means

PackageMeta calls getFile on the validated shasums_signature_url to fetch the detached cryptographic signature and the HTTP fetch failed — transport error or non-200 status. The signature is required for trust verification of the checksums, so the install aborts via errQueryFailed (ErrQueryFailed).

Source

Thrown at internal/getproviders/registry_client.go:348

	if err != nil {
		return PackageMeta{}, c.errQueryFailed(
			provider,
			fmt.Errorf("failed to retrieve authentication checksums for provider: %s", err),
		)
	}
	signatureURL, err := url.Parse(body.SHA256SumsSignatureURL)
	if err != nil {
		return PackageMeta{}, fmt.Errorf("registry response includes invalid SHASUMS signature URL: %s", err)
	}
	signatureURL = resp.Request.URL.ResolveReference(signatureURL)
	if signatureURL.Scheme != "http" && signatureURL.Scheme != "https" {
		return PackageMeta{}, fmt.Errorf("registry response includes invalid SHASUMS signature URL: must use http or https scheme")
	}
	signature, err := c.getFile(signatureURL)
	if err != nil {
		return PackageMeta{}, c.errQueryFailed(
			provider,
			fmt.Errorf("failed to retrieve cryptographic signature for provider: %s", err),
		)
	}

	keys := make([]SigningKey, len(body.SigningKeys.GPGPublicKeys))
	for i, key := range body.SigningKeys.GPGPublicKeys {
		keys[i] = *key
	}

	ret.Authentication = PackageAuthenticationAll(
		NewMatchingChecksumAuthentication(document, body.Filename, checksum),
		NewArchiveChecksumAuthentication(ret.TargetPlatform, checksum),
		NewSignatureAuthentication(document, signature, keys),
	)

	return ret, nil
}

// findClosestProtocolCompatibleVersion searches for the provider version with the closest protocol match.

View on GitHub (pinned to c9def3e214)

Solutions

  1. Retry after confirming the signature URL is fetchable (curl).
  2. Increase TF_REGISTRY_CLIENT_TIMEOUT / TF_REGISTRY_DISCOVERY_RETRY.
  3. Open egress to the signature host / configure HTTPS_PROXY.
  4. Refresh expired signed URLs before the Terraform run.

Example fix

# before
export TF_REGISTRY_DISCOVERY_RETRY=1
# after
export TF_REGISTRY_DISCOVERY_RETRY=3
Defensive patterns

Strategy: retry

Validate before calling

// Informational pre-flight: can we reach the signature host?
func signatureHostReachable(rawURL string) error {
    u, err := url.Parse(rawURL)
    if err != nil {
        return err
    }
    conn, err := net.DialTimeout("tcp", u.Host, 5*time.Second)
    if err != nil {
        return err
    }
    conn.Close()
    return nil
}

Type guard

func isSignatureFetchErr(err error) bool {
    var qf getproviders.ErrQueryFailed
    if errors.As(err, &qf) {
        return strings.Contains(qf.Wrapped.Error(), "failed to retrieve cryptographic signature")
    }
    return false
}

Try / catch

var meta getproviders.PackageMeta
var err error
for i := 0; i < 3; i++ {
    meta, err = client.PackageMeta(ctx, provider, ver, plat)
    if err == nil || !isSignatureFetchErr(err) {
        break
    }
    time.Sleep(backoff(i))
}

Prevention

When it happens

Trigger: The signature URL is valid http(s) but unreachable: connection refused, DNS failure, TLS error, timeout, 403/404/500, or body read failure. Distinct from a bad signature *content* — this is a fetch-layer failure.

Common situations: Signature host (often a separate CDN/keyserver) down or firewalled; signed URL expired; corporate proxy blocks the signature host; TF_REGISTRY_CLIENT_TIMEOUT too low; transient 5xx on the signature endpoint.

Related errors

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