hashicorp/terraform · error

a network issue prevented cloud configuration; %w

Error message

a network issue prevented cloud configuration; %w

What it means

Returned in backend Configure at backend.go:278 when service discovery (b.services.Discover) returns an error matching disco.ErrServiceDiscoveryNetworkRequest via errors.As. The original network error is wrapped with %w so callers can still inspect it. It fires before any token logic, specifically when the HCP Terraform / Terraform Enterprise hostname cannot be contacted.

Source

Thrown at internal/cloud/backend.go:278

	// We want to handle errors from URL normalization and service discovery in
	// the same way. So we only perform each step if there wasn't a previous
	// error, and use the same block to handle errors from anywhere in the
	// process.
	hostname, err := svchost.ForComparison(b.Hostname)
	if err == nil {
		host, err = b.services.Discover(hostname)

		if err == nil {
			// The discovery request worked, so cache the full results.
			b.ServicesHost = host

			// Find the TFE API service URL
			tfcService, err = host.ServiceURL(tfeServiceID)
		} else {
			// 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)
			}
		}
	}

	// Handle any errors from URL normalization and service discovery before we continue.
	if err != nil {
		diags = diags.Append(tfdiags.AttributeValue(
			tfdiags.Error,
			strings.ToUpper(err.Error()[:1])+err.Error()[1:],
			"", // no description is needed here, the error is clear
			cty.Path{cty.GetAttrStep{Name: "hostname"}},
		))
		return diags
	}

	// Token time. First, see if the configuration had one:
	token := config.token

View on GitHub (pinned to c9def3e214)

Solutions

1. Verify the hostname in the cloud block resolves and is reachable: curl -v https://<host>.
2. Connect to the VPN or network required to reach your TFE install.
3. Configure HTTPS_PROXY / TF_PROXY for corporate proxies and retry.
4. Check DNS and retry if the failure is transient.

Example fix

// before
cloud { hostname = "app.terraform.io " organization = "acme" } // trailing space / unreachable

// after
cloud { hostname = "app.terraform.io" organization = "acme" }

// Reachability check before terraform init.
func cloudReachable(host string) error {
    u := "https://" + host + "/.well-known/terraform.json"
    resp, err := http.Get(u) // use configured client/proxy in production
    if err != nil { return err }
    defer resp.Body.Close()
    return nil
}

// Narrow the wrapped network error.
var discoNet *disco.ErrServiceDiscoveryNetworkRequest
if errors.As(err, &discoNet) { /* network issue */ }

// Retry backend Configure on network discovery errors.
for i := 0; i < 5; i++ {
    diags := b.Configure(ctx)
    if !diags.HasErrors() { break }
    if !isNetworkDiscoveryErr(diags.Err()) { return diags }
    time.Sleep(backoff(i))
}

When it happens

Trigger: terraform init / terraform plan with a cloud backend whose hostname is unreachable: DNS failure, TCP refused, TLS handshake failure, or a corporate proxy blocking the discovery request.

Common situations: Wrong hostname in the cloud block; on-prem TFE offline or behind a VPN not connected; corporate proxy/firewall blocking app.terraform.io; transient ISP/DNS outage; typo like 'app.terraform.io ' with trailing space.

Related errors

• operation timed out
• %s returned an unexpected error: %s
• operation timed out
• your version of Terraform Enterprise does not support key-va
• {joined API error payload}

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