hashicorp/terraform · error · ErrQueryFailed

${resp.Status}

Error message

${resp.Status}

What it means

Thrown by the plugin manifest HTTP client (BasePluginClient, pluginshared package) when the manifest query returned an HTTP status that is neither 200, 304, nor 404. The default branch wraps resp.Status (the HTTP status line, e.g. '429 Too Many Requests') in an ErrQueryFailed. This client is used to resolve the plugin release manifest (versions, build artifacts) from a releases server.

Solutions

1. Retry `terraform init` — 429/5xx are usually transient; the client already uses retryablehttp for some requests.
2. Set CLI args / network config to route through an allowed mirror (TF_PLUGIN_CACHE_DIR, plugin_installation filesystem mirror).
3. Check for a proxy or firewall blocking the releases host; allowlist it.
4. Pin provider versions with `terraform providers lock` to avoid live manifest queries.

Example fix

# before
$ terraform init   # -> ErrQueryFailed: 429 Too Many Requests

# after
# wait and retry, or pre-lock providers offline
$ terraform providers lock && terraform init

# shell: pre-check manifest endpoint reachability
$ curl -sS -o /dev/null -w '%{http_code}\n' https://releases.hashicorp.com/index.json

# bash: retry init on transient manifest failures; fall back to locked providers
for i in 1 2 3; do
  terraform init && break
  sleep 5
done
# fallback: use pre-locked providers offline
terraform init -plugin-dir=.terraform/plugins

When it happens

Trigger: The releases/manifest endpoint returned 5xx (server error), 429 (rate limit), 403 (forbidden/CI network policy), or another unexpected code during `terraform init` plugin discovery.

Common situations: Rate-limiting from releases.hashicorp.com in CI. Corporate proxy/firewall returning 403/502. Transient 5xx on the releases server. A misconfigured plugin installation mirror URL returning an error page.

Related errors

• a network issue prevented cloud configuration;
• a network issue prevented cloud configuration;
• bucket not exists
• couldn't read information for cloud run
• couldn't read plan data for cloud run

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

Appendix: source

Thrown at internal/pluginshared/client.go:196

			inner: err,
		}
	}
	defer resp.Body.Close()

	switch resp.StatusCode {
	case http.StatusOK:
		manifest, err := decodeManifest(resp.Body)
		if err != nil {
			return nil, err
		}
		return manifest, nil
	case http.StatusNotModified:
		return nil, nil
	case http.StatusNotFound:
		return nil, ErrPluginNotSupported
	default:
		return nil, ErrQueryFailed{
			inner: errors.New(resp.Status),
		}
	}
}

// DownloadFile gets the URL at the specified path or URL and writes the
// contents to the specified Writer.
func (b BasePluginClient) DownloadFile(pathOrURL string, writer io.Writer) error {
	url, err := b.resolveManifestURL(pathOrURL)
	if err != nil {
		return err
	}
	req, err := retryablehttp.NewRequestWithContext(b.ctx, "GET", url.String(), nil)
	if err != nil {
		return fmt.Errorf("invalid URL %q was provided by the %s manifest: %w", url, b.pluginName, err)
	}
	resp, err := b.httpClient.Do(req)
	if err != nil {
		if errors.Is(err, context.Canceled) {

View on GitHub (pinned to d32a084675)