hashicorp/terraform · error · ErrQueryFailed

failed to retrieve authentication checksums for provider

Error message

failed to retrieve authentication checksums for provider: %s

What it means

Thrown when fetching the SHA256SUMS document from the resolved shasums_url fails. Unlike the URL parse/scheme errors this is a transport/HTTP failure and is wrapped by errQueryFailed, so it commonly reflects a network or server problem rather than a malformed response.

Solutions

Retry the operation after a short delay for transient network/5xx failures
Verify the shasums_url is reachable and returns 200 (curl it from the same host)
Check DNS/TLS connectivity to the registry and any redirect target
If airgapped, mirror the SHA256SUMS artifact locally and point the registry at it

Defensive patterns

Strategy: retry

Validate before calling

// Not a validation error; pre-flight reachability can reduce surprises.
resp, err := http.Head(shasumsURL.String())
if err != nil || resp.StatusCode >= 400 {
    log.Printf("SHASUMS endpoint unreachable: %v status=%v", err, respStatus(resp))
}

Try / catch

var doc []byte
err := retry.Do(func() error {
    var err error
    doc, err = c.getFile(shasumsURL)
    return err
}, retry.Attempts(3), retry.LastErrorOnly(true))
if err != nil {
    return fmt.Errorf("failed to retrieve SHASUMS after retries: %w", err)
}

Prevention

Add bounded retry with backoff for SHASUMS fetches to absorb transient registry errors
Verify registry/mirror connectivity and TLS from the host before a run
Mirror the SHA256SUMS artifact locally for airgapped environments

When it happens

Trigger: c.getFile(shasumsURL) returned a non-nil error — HTTP 4xx/5xx, DNS failure, connection refused, TLS error, timeout, or a truncated body.

Common situations: Registry/mirror outage; 404 for the SHA256SUMS file for this version; transient network failure; TLS certificate problem; an airgapped environment where the shasums host is unreachable.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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

Appendix: source

Thrown at internal/getproviders/registry_client.go:333

		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" {
		return PackageMeta{}, fmt.Errorf("registry response includes invalid SHASUMS URL: must use http or https scheme")
	}
	document, err := c.getFile(shasumsURL)
	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),
		)
	}

View on GitHub (pinned to d32a084675)