hashicorp/terraform · error · ErrQueryFailed

failed to retrieve authentication checksums for provider: %s

Error message

failed to retrieve authentication checksums for provider: %s

What it means

PackageMeta calls getFile on the (validated) shasums_url to download the SHASUMS checksum document and the HTTP fetch failed — either a transport error or a non-200 status (getFile returns its own error string for non-200). The package install is aborted via errQueryFailed (ErrQueryFailed).

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

Solutions

  1. Retry the install after confirming the shasums_url is reachable in a browser or curl.
  2. Raise TF_REGISTRY_CLIENT_TIMEOUT and/or TF_REGISTRY_DISCOVERY_RETRY.
  3. Check proxy/firewall egress to the checksum host; configure HTTPS_PROXY if needed.
  4. If using signed URLs, ensure they have not expired before Terraform runs.

Example fix

# before
export TF_REGISTRY_CLIENT_TIMEOUT=10
# after
export TF_REGISTRY_CLIENT_TIMEOUT=60
Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight reachability check for the shasums host (informational only).
func hostReachable(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 isShasumsFetchErr(err error) bool {
    var qf getproviders.ErrQueryFailed
    if errors.As(err, &qf) {
        return strings.Contains(qf.Wrapped.Error(), "failed to retrieve authentication checksums")
    }
    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 || !isShasumsFetchErr(err) {
        break
    }
    time.Sleep(backoff(i))
}

Prevention

When it happens

Trigger: The shasums_url is valid http(s) but unreachable: connection refused, DNS failure, TLS error, timeout, 403/404/500 from the host, or the body read failed.

Common situations: Registry is temporarily down or returning 403 (auth/signed URLs expired); corporate proxy blocking the checksum host; the host differs from the registry host (CDN) and is firewalled; TF_REGISTRY_CLIENT_TIMEOUT too low for a slow artifact store; transient 5xx.

Understand the failure class

Related errors

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