{"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":"console","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/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/stacks.go#L240-L276","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the hostname is reachable: curl https://<hostname>/.well-known/terraform.json.","Set TF_STACKS_HOSTNAME (or TF_CLOUD_HOSTNAME) explicitly to the correct value.","Configure HTTPS_PROXY / proxy settings if behind a corporate proxy.","Fix DNS/TLS (trusted CA, valid cert) for private TFE instances.","Retry once transient network blips are ruled out."],"exampleFix":"// before\n$ terraform stacks init\na network issue prevented cloud configuration; ...\n// after\n$ export TF_CLOUD_HOSTNAME=app.terraform.io\n$ HTTPS_PROXY=http://proxy.corp:8080 terraform stacks init","handlingStrategy":"retry","validationCode":"// Pre-flight: probe the stacks cloud hostname discovery endpoint before running\npackage main\n\nfunc preflightStacksHost(hostname string) error {\n\tu := \"https://\" + hostname + \"/.well-known/terraform.json\"\n\tresp, err := http.Get(u)\n\tif err != nil { return fmt.Errorf(\"cannot reach %s: %w\", u, err) }\n\tresp.Body.Close()\n\tif resp.StatusCode >= 500 { return fmt.Errorf(\"discovery endpoint unhealthy (%d)\", resp.StatusCode) }\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set TF_STACKS_HOSTNAME or TF_CLOUD_HOSTNAME explicitly to avoid DNS/hostname guesswork.","Configure HTTPS_PROXY in corporate networks so discovery requests can egress.","Ensure TLS CAs are trusted for private TFE instances."],"tags":["stacks","cloud","network","service-discovery","dns"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}