{"record":{"id":"e171ced9f2c07bc0","repo":"hashicorp/terraform","slug":"a-network-issue-prevented-cloud-configuration-w","errorCode":null,"errorMessage":"a network issue prevented cloud configuration; %w","messagePattern":"a network issue prevented cloud configuration; %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/backend.go","lineNumber":278,"sourceCode":"\t// We want to handle errors from URL normalization and service discovery in\n\t// the same way. So we only perform each step if there wasn't a previous\n\t// error, and use the same block to handle errors from anywhere in the\n\t// process.\n\thostname, err := svchost.ForComparison(b.Hostname)\n\tif err == nil {\n\t\thost, err = b.services.Discover(hostname)\n\n\t\tif err == nil {\n\t\t\t// The discovery request worked, so cache the full results.\n\t\t\tb.ServicesHost = host\n\n\t\t\t// Find the TFE API service URL\n\t\t\ttfcService, err = host.ServiceURL(tfeServiceID)\n\t\t} else {\n\t\t\t// Network errors from Discover() can read like non-sequiters, so we wrap em.\n\t\t\tvar serviceDiscoErr *disco.ErrServiceDiscoveryNetworkRequest\n\t\t\tif errors.As(err, &serviceDiscoErr) {\n\t\t\t\terr = fmt.Errorf(\"a network issue prevented cloud configuration; %w\", err)\n\t\t\t}\n\t\t}\n\t}\n\n\t// Handle any errors from URL normalization and service discovery before we continue.\n\tif err != nil {\n\t\tdiags = diags.Append(tfdiags.AttributeValue(\n\t\t\ttfdiags.Error,\n\t\t\tstrings.ToUpper(err.Error()[:1])+err.Error()[1:],\n\t\t\t\"\", // no description is needed here, the error is clear\n\t\t\tcty.Path{cty.GetAttrStep{Name: \"hostname\"}},\n\t\t))\n\t\treturn diags\n\t}\n\n\t// Token time. First, see if the configuration had one:\n\ttoken := config.token\n","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/cloud/backend.go#L260-L296","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before — typo in hostname\nterraform {\n  cloud {\n    hostname     = \"app.terraform.ioo\"\n    organization = \"my-org\"\n  }\n}\n\n# after — correct hostname\nterraform {\n  cloud {\n    hostname     = \"app.terraform.io\"\n    organization = \"my-org\"\n  }\n}","handlingStrategy":"retry","validationCode":"// Before Configure, verify hostname is reachable\nimport \"net/http\"\nresp, err := http.Get(fmt.Sprintf(\"https://%s/.well-known/terraform.json\", hostname))\nif err != nil {\n    return fmt.Errorf(\"hostname %s is not reachable: %w\", hostname, err)\n}\nresp.Body.Close()","typeGuard":null,"tryCatchPattern":"// The cloud backend already wraps disco network errors.\n// At the caller level, check for the wrapped error:\nfor _, diag := range diags {\n    if strings.Contains(diag.Description().Summary, \"network issue prevented cloud configuration\") {\n        // Implement retry with backoff, or prompt user to check network\n    }\n}","preventionTips":["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."],"tags":["terraform","cloud-backend","network","service-discovery","dns","tls","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}