{"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/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote/backend.go#L199-L235","documentation":"Returned by Remote.ServiceDiscoveryAliases when svchost.ForComparison(b.hostname) fails for the user-configured backend hostname. Unlike index 397 this IS reachable from user input: a malformed hostname in the backend 'hostname' attribute triggers it. The comment notes the value was expected to already be validated.","triggerScenarios":"ServiceDiscoveryAliases() is called with b.hostname containing an invalid RFC hostname: underscores, uppercase (svchost lowercases but still validates), trailing dots, invalid TLD, or non-ASCII without punycode.","commonSituations":"User puts 'app.terraform.io.' (trailing dot), 'app_tf.io' (underscore), an IP address, or a typo like 'app terraform.io' in the remote backend hostname block; self-hosted TFE with a non-DNS hostname; or a config templating bug injecting whitespace.","solutions":["Set hostname to a clean RFC-1123 value (lowercase, no underscores, no trailing dot).","For on-prem TFE, use the exact DNS name of the install.","Remove any surrounding quotes/whitespace introduced by templating.","If using a non-standard port, put it in the URL/path, not the hostname attribute."],"exampleFix":"// before\nterraform {\n  backend \"remote\" {\n    hostname = \"app.terraform.io.\"  // trailing dot invalid\n  }\n}\n// after\nterraform {\n  backend \"remote\" {\n    hostname = \"app.terraform.io\"\n  }\n}","handlingStrategy":"validation","validationCode":"// Validate the user-supplied hostname before configuring the backend\nimport \"github.com/hashicorp/terraform-svchost\"\n\nfunc validateHostname(h string) error {\n  if _, err := svchost.ForComparison(h); err != nil {\n    return fmt.Errorf(\"invalid backend hostname %q: %w\", h, err)\n  }\n  return nil\n}\n\n// usage\nif err := validateHostname(cfg.Hostname); err != nil { return err }","typeGuard":null,"tryCatchPattern":"if _, err := b.ServiceDiscoveryAliases(); err != nil && strings.Contains(err.Error(), \"hostname is not in the correct format\") {\n    // surface a clear 'fix your hostname attribute' message\n}","preventionTips":["Validate the hostname with svchost.ForComparison before passing it to the backend.","Use lowercase RFC-1123 names, no underscores, no trailing dots.","Linter/CI check the backend block hostname format.","Templating must not inject whitespace or quotes into the hostname."],"tags":["terraform-remote-backend","host-validation","configuration","service-discovery"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}