{"record":{"id":"3c5d117cf4ee7711","repo":"hashicorp/terraform","slug":"a-network-issue-prevented-cloud-configuration-w-3c5d11","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/command/stacks.go","lineNumber":258,"sourceCode":"\tif diags.HasErrors() {\n\t\treturn diags\n\t}\n\n\thostname, err := svchost.ForComparison(displayHostname)\n\tif err != nil {\n\t\treturn diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,\n\t\t\t\"Hostname string cannot be parsed into a svc.Hostname\",\n\t\t\terr.Error(),\n\t\t))\n\t}\n\n\thost, err := cb.Services().Discover(hostname)\n\tif err != nil {\n\t\t// Network errors from Discover() can read like non-sequiters, so we wrap em.\n\t\tvar serviceDiscoErr *disco.ErrServiceDiscoveryNetworkRequest\n\t\tif errors.As(err, &serviceDiscoErr) {\n\t\t\terr = fmt.Errorf(\"a network issue prevented cloud configuration; %w\", err)\n\t\t}\n\n\t\treturn diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,\n\t\t\t\"Hostname discovery failed\",\n\t\t\tfmt.Sprintf(\"%s\\n\\nSet TF_STACKS_HOSTNAME or TF_CLOUD_HOSTNAME to specify the intended host.\", err.Error()),\n\t\t))\n\t}\n\n\t// The discovery request worked, so cache the full results.\n\tcb.ServicesHost = host\n\n\ttoken := os.Getenv(\"TF_STACKS_TOKEN\")\n\tif strings.TrimSpace(token) == \"\" {\n\t\t// attempt to read from the credentials file\n\t\ttoken, err = cloud.CliConfigToken(hostname, cb.Services())\n\t\tif err != nil {\n\t\t\t// some commands like stacks init and validate could be run without a token so allow it without errors","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/stacks.go#L240-L276","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set TF_STACKS_HOSTNAME or TF_CLOUD_HOSTNAME to the correct, reachable host (the error message itself prompts this).","Verify network egress: `curl -v https://<hostname>/.well-known/terraform.json` from the same shell.","Configure proxy env vars (HTTPS_PROXY) and add the host to NO_PROXY only if it is internal.","Check DNS resolution and TLS trust store for the hostname."],"exampleFix":"# before: unreachable default host\n export TF_CLOUD_HOSTNAME=ap.terraform.io\n\n# after\n export TF_CLOUD_HOSTNAME=app.terraform.io\n curl -fsS https://app.terraform.io/.well-known/terraform.json","handlingStrategy":"validation","validationCode":"// Pre-flight: confirm the discovery endpoint is reachable.\nurl := \"https://\" + hostname + \"/.well-known/terraform.json\"\nresp, err := http.Head(url)\nif err != nil {\n    return fmt.Errorf(\"HCP discovery unreachable; set TF_STACKS_HOSTNAME or check proxy: %w\", err)\n}\nresp.Body.Close()","typeGuard":null,"tryCatchPattern":"host, err := cb.Services().Discover(hostname)\nif err != nil {\n    var netErr *disco.ErrServiceDiscoveryNetworkRequest\n    if errors.As(err, &netErr) {\n        // network-layer: retry with backoff or surface proxy guidance\n        return fmt.Errorf(\"network issue contacting HCP at %s; verify HTTPS_PROXY/DNS: %w\", hostname, err)\n    }\n    return fmt.Errorf(\"non-network discovery failure for %s: %w\", hostname, err)\n}","preventionTips":["Always set TF_STACKS_HOSTNAME / TF_CLOUD_HOSTNAME explicitly in automation.","Add `*.terraform.io` (or your HCP host) to proxy allowlists and NO_PROXY accordingly.","Pre-flight `curl https://<host>/.well-known/terraform.json` from the runner.","Validate TLS trust store on CI images that use custom CAs."],"tags":["terraform","stacks","hcp-cloud","network","discovery","proxy","tls"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}