hashicorp/terraform · error

a network issue prevented cloud configuration; %w

Error message

a network issue prevented cloud configuration; %w

What it means

Wrapped error during StacksCommand.discoverAndConfigure when cb.Services().Discover(hostname) fails with a disco.ErrServiceDiscoveryNetworkRequest. This is the HCP Terraform/TFE service-discovery step for the stacks cloud backend: Terraform GETs /.well-known/terraform.json on the configured hostname. A network-class error is rewrapped to make clear it is connectivity, not a config problem. The user-facing diagnostic also suggests setting TF_STACKS_HOSTNAME or TF_CLOUD_HOSTNAME.

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

Solutions

1. Verify the hostname is reachable: curl https://<hostname>/.well-known/terraform.json.
2. Set TF_STACKS_HOSTNAME (or TF_CLOUD_HOSTNAME) explicitly to the correct value.
3. Configure HTTPS_PROXY / proxy settings if behind a corporate proxy.
4. Fix DNS/TLS (trusted CA, valid cert) for private TFE instances.
5. Retry once transient network blips are ruled out.

Example fix

// before
$ terraform stacks init
a network issue prevented cloud configuration; ...
// after
$ export TF_CLOUD_HOSTNAME=app.terraform.io
$ HTTPS_PROXY=http://proxy.corp:8080 terraform stacks init

// Pre-flight: probe the stacks cloud hostname discovery endpoint before running
package main

func preflightStacksHost(hostname string) error {
	u := "https://" + hostname + "/.well-known/terraform.json"
	resp, err := http.Get(u)
	if err != nil { return fmt.Errorf("cannot reach %s: %w", u, err) }
	resp.Body.Close()
	if resp.StatusCode >= 500 { return fmt.Errorf("discovery endpoint unhealthy (%d)", resp.StatusCode) }
	return nil
}

When it happens

Trigger: Running a stacks command (init/plan/apply/validate) when the discovery request to the configured hostname fails at the network layer — DNS resolution failure, connection refused/timeout, TLS handshake error, or proxy blocking the request. errors.As narrows to ErrServiceDiscoveryNetworkRequest before wrapping.

Common situations: Corporate proxy/firewall blocking the hostname; wrong hostname (typo in TF_CLOUD_HOSTNAME/TF_STACKS_HOSTNAME); DNS outage; self-signed/expired TLS cert on a private TFE instance; air-gapped environment; VPN not connected.

Related errors

• a network issue prevented cloud configuration; %w
• a network issue prevented cloud configuration; %w
• Failed to get existing workspaces: %s
• consul lock was lost
• operation timed out

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