hashicorp/terraform · error

a network issue prevented cloud configuration;

Error message

a network issue prevented cloud configuration; %w

What it means

Thrown from the stacks command's HCP/Cloud discovery when cb.Services().Discover(hostname) fails with a disco.ErrServiceDiscoveryNetworkRequest. The wrapper is only applied after errors.As confirms it is a network-layer failure (DNS, TLS, connection refused, timeout), not a 4xx discovery response. The original error is preserved with %w.

Solutions

1. Set TF_STACKS_HOSTNAME or TF_CLOUD_HOSTNAME to the correct, reachable host (the error message itself prompts this).
2. Verify network egress: `curl -v https://<hostname>/.well-known/terraform.json` from the same shell.
3. Configure proxy env vars (HTTPS_PROXY) and add the host to NO_PROXY only if it is internal.
4. Check DNS resolution and TLS trust store for the hostname.

Example fix

# before: unreachable default host
 export TF_CLOUD_HOSTNAME=ap.terraform.io

# after
 export TF_CLOUD_HOSTNAME=app.terraform.io
 curl -fsS https://app.terraform.io/.well-known/terraform.json

// Pre-flight: confirm the discovery endpoint is reachable.
url := "https://" + hostname + "/.well-known/terraform.json"
resp, err := http.Head(url)
if err != nil {
    return fmt.Errorf("HCP discovery unreachable; set TF_STACKS_HOSTNAME or check proxy: %w", err)
}
resp.Body.Close()

host, err := cb.Services().Discover(hostname)
if err != nil {
    var netErr *disco.ErrServiceDiscoveryNetworkRequest
    if errors.As(err, &netErr) {
        // network-layer: retry with backoff or surface proxy guidance
        return fmt.Errorf("network issue contacting HCP at %s; verify HTTPS_PROXY/DNS: %w", hostname, err)
    }
    return fmt.Errorf("non-network discovery failure for %s: %w", hostname, err)
}

When it happens

Trigger: Terraform Stacks trying to discover the HCP Terraform / Terraform Cloud service discovery document at https://<hostname>/.well-known/terraform.json and the request never completes at the network layer (no DNS, TLS handshake fails, proxy blocks it, host unreachable).

Common situations: Corporate proxy or firewall blocking egress to app.terraform.io; misconfigured HTTPS_PROXY / NO_PROXY; on-prem air-gapped install with no route to HCP; TLS interception breaking the cert chain; typo in TF_STACKS_HOSTNAME / TF_CLOUD_HOSTNAME producing an unresolvable host.

Related errors

• a network issue prevented cloud configuration;
• bucket not exists
• Connection Error: StatusCode
• 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/3c5d117cf4ee7711. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/stacks.go:258

	if diags.HasErrors() {
		return diags
	}

	hostname, err := svchost.ForComparison(displayHostname)
	if err != nil {
		return diags.Append(tfdiags.Sourceless(
			tfdiags.Error,
			"Hostname string cannot be parsed into a svc.Hostname",
			err.Error(),
		))
	}

	host, err := cb.Services().Discover(hostname)
	if err != nil {
		// Network errors from Discover() can read like non-sequiters, so we wrap em.
		var serviceDiscoErr *disco.ErrServiceDiscoveryNetworkRequest
		if errors.As(err, &serviceDiscoErr) {
			err = fmt.Errorf("a network issue prevented cloud configuration; %w", err)
		}

		return diags.Append(tfdiags.Sourceless(
			tfdiags.Error,
			"Hostname discovery failed",
			fmt.Sprintf("%s\n\nSet TF_STACKS_HOSTNAME or TF_CLOUD_HOSTNAME to specify the intended host.", err.Error()),
		))
	}

	// The discovery request worked, so cache the full results.
	cb.ServicesHost = host

	token := os.Getenv("TF_STACKS_TOKEN")
	if strings.TrimSpace(token) == "" {
		// attempt to read from the credentials file
		token, err = cloud.CliConfigToken(hostname, cb.Services())
		if err != nil {
			// some commands like stacks init and validate could be run without a token so allow it without errors

View on GitHub (pinned to d32a084675)