{"record":{"id":"29e945514ae1f2ca","repo":"hashicorp/terraform","slug":"failed-to-create-backend-alias-to-target-q-the-h","errorCode":null,"errorMessage":"failed to create backend alias to target %q. The hostname is not in the correct format","messagePattern":"failed to create backend alias to target %q\\. The hostname is not in the correct format","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend.go","lineNumber":217,"sourceCode":"\t\t\tcty.Path{cty.GetAttrStep{Name: \"workspaces\"}},\n\t\t))\n\t}\n\n\treturn obj, diags\n}\n\nfunc (b *Remote) ServiceDiscoveryAliases() ([]backendrun.HostAlias, error) {\n\taliasHostname, err := svchost.ForComparison(genericHostname)\n\tif err != nil {\n\t\t// This should never happen because the hostname is statically defined.\n\t\treturn nil, fmt.Errorf(\"failed to create backend alias from alias %q. The hostname is not in the correct format. This is a bug in the backend\", genericHostname)\n\t}\n\n\ttargetHostname, err := svchost.ForComparison(b.hostname)\n\tif err != nil {\n\t\t// This should never happen because the 'to' alias is the backend host, which has likely\n\t\t// already been evaluated as a svchost.Hostname by now\n\t\treturn nil, fmt.Errorf(\"failed to create backend alias to target %q. The hostname is not in the correct format\", b.hostname)\n\t}\n\n\treturn []backendrun.HostAlias{\n\t\t{\n\t\t\tFrom: aliasHostname,\n\t\t\tTo:   targetHostname,\n\t\t},\n\t}, nil\n}\n\n// Configure implements backend.Backend.\nfunc (b *Remote) Configure(obj cty.Value) tfdiags.Diagnostics {\n\tvar diags tfdiags.Diagnostics\n\tif obj.IsNull() {\n\t\treturn diags\n\t}\n\n\t// Get the hostname.","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend.go#L199-L235","documentation":"Thrown by Remote.ServiceDiscoveryAliases when svchost.ForComparison rejects b.hostname. The comment marks this as a 'should never happen' invariant: the hostname was already validated as a svchost.Hostname earlier during service discovery. It surfaces only if the stored hostname is somehow not a valid-for-comparison RFC host string at alias-construction time.","triggerScenarios":"svchost.ForComparison(b.hostname) returns a non-nil error when constructing the service-discovery alias mapping the generic host to the configured backend host. This requires b.hostname to fail host parsing despite having passed discovery.","commonSituations":"A bug in the backend or an upstream change to svchost validation; a custom TFE hostname containing characters that ForComparison rejects (e.g. underscore, trailing dot, or IDN form not normalized); corrupted hostname after a partial reconfigure.","solutions":["Verify the configured hostname in the backend 'host'/'address' block is a plain lowercase RFC-1123 host (no scheme, port, underscore, or trailing dot).","Re-run 'terraform init' to force service discovery to re-validate and overwrite b.hostname.","If you build/embed Terraform, audit any code path that sets b.hostname without going through svchost.ForComparison first.","Report as a bug: the comment itself states this should never happen, so a real occurrence indicates a broken invariant worth filing upstream."],"exampleFix":"// before: raw user host assigned directly\nb.hostname = cfg.Host\n// after: validate via svchost before storing\nh, err := svchost.ForComparison(cfg.Host)\nif err != nil {\n    return fmt.Errorf(\"invalid hostname %q: %w\", cfg.Host, err)\n}\nb.hostname = h.String()","handlingStrategy":"validation","validationCode":"// Validate the hostname is a parseable svchost before storing/using it.\nimport \"github.com/hashicorp/terraform-svchost\"\n\nfunc validateBackendHostname(raw string) error {\n    if _, err := svchost.ForComparison(raw); err != nil {\n        return fmt.Errorf(\"hostname %q is not valid: %w\", raw, err)\n    }\n    return nil\n}\n\n// call during backend config validation, before ServiceDiscoveryAliases()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always run hostnames through svchost.ForComparison at the config boundary so malformed values are rejected before they reach ServiceDiscoveryAliases.","Never assign b.hostname from user input without validation; treat the field as already-normalized.","Treat a hit on this 'should never happen' branch as a bug to file, not an expected runtime error."],"tags":["backend","remote-backend","service-discovery","hostname","invariant","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}