What causes "a network issue prevented cloud configuration; %w" in hashicorp/terraform?

Verify the hostname is correct: `curl https:// /api/v2/ping` should return a successful response.

a network issue prevented cloud configuration;

Error message

a network issue prevented cloud configuration; %w

What it means

During cloud backend configuration, Terraform performs service discovery against the configured hostname. When the discovery request fails with a network-level error (typed as *disco.ErrServiceDiscoveryNetworkRequest), the error is wrapped with 'a network issue prevented cloud configuration' to make the root cause clearer to the user. The wrapped error is then surfaced as a diagnostic on the 'hostname' attribute.

Solutions

Verify the hostname is correct: `curl https://<hostname>/api/v2/ping` should return a successful response.
Check DNS resolution: `nslookup <hostname>` or `dig <hostname>`.
Ensure no proxy or firewall blocks HTTPS traffic to the hostname.
For self-hosted TFE, verify the instance is running and the TLS certificate is valid.
Set TF_CLOUD_HOSTNAME correctly if using environment variables.

Example fix

# before — typo in hostname
terraform {
  cloud {
    hostname     = "app.terraform.ioo"
    organization = "my-org"
  }
}

# after — correct hostname
terraform {
  cloud {
    hostname     = "app.terraform.io"
    organization = "my-org"
  }
}

Defensive patterns

Strategy: retry

Validate before calling

// Before Configure, verify hostname is reachable
import "net/http"
resp, err := http.Get(fmt.Sprintf("https://%s/.well-known/terraform.json", hostname))
if err != nil {
    return fmt.Errorf("hostname %s is not reachable: %w", hostname, err)
}
resp.Body.Close()

Try / catch

// The cloud backend already wraps disco network errors.
// At the caller level, check for the wrapped error:
for _, diag := range diags {
    if strings.Contains(diag.Description().Summary, "network issue prevented cloud configuration") {
        // Implement retry with backoff, or prompt user to check network
    }
}

Prevention

Verify hostname resolution and HTTPS connectivity before running 'terraform init'.
Configure proxy settings (HTTP_PROXY, HTTPS_PROXY) if behind a corporate firewall.
Use `terraform login <hostname>` to verify connectivity and authenticate in one step.
For self-hosted TFE, ensure the TLS certificate is trusted by the system CA store.

When it happens

Trigger: Calling b.services.Discover(hostname) at backend.go:266 returns an error that satisfies errors.As for *disco.ErrServiceDiscoveryNetworkRequest. This occurs when DNS resolution fails, the connection is refused, times out, or TLS handshake fails during the discovery HTTPS request to the configured hostname.

Common situations: Incorrect hostname in the cloud block (typo, wrong TFE instance FQDN). DNS resolution failure in the user's network environment. A proxy or firewall blocking HTTPS to the TFE/HCP Terraform host. The TFE instance is down or unreachable. TLS certificate issues on a self-hosted TFE instance.

Related errors

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

Appendix: 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 d32a084675)