hashicorp/terraform · critical

failed to create backend alias from alias

Error message

failed to create backend alias from alias %q. The hostname is not in the correct format. This is a bug in the backend

What it means

Thrown by the Terraform Cloud/Enterprise remote backend's ServiceDiscoveryAliases when svchost.ForComparison rejects the statically-defined genericHostname constant ("localterraform.com"). The code comment is explicit: this should never happen because the hostname is a compile-time constant. Reaching this error indicates the constant itself is malformed — i.e. a bug shipped in the backend, not a user configuration problem.

Solutions

1. If you are running an official Terraform build, file a bug report — this path is documented as unreachable.
2. If running a fork/custom build, restore genericHostname to the valid literal "localterraform.com" (or another RFC-compliant hostname).
3. Check whether an svchost dependency upgrade changed validation rules; pin or update hashicorp/go-svchost to a compatible version.
4. As a user there is no configuration fix — report the bug to the backend maintainer.
5. Verify no build-time flag/ldflag is overriding the constant.

Example fix

// backend.go — the constant must be a valid hostname
// before (invalid, triggers the bug):
//   genericHostname = "local_terraform.com"   // underscore illegal
// after:
const genericHostname = "localterraform.com"

// For a statically-defined hostname, validate at startup so an invalid constant fails fast and clearly.
import "github.com/hashicorp/go-svchost"

func init() {
  if _, err := svchost.ForComparison(genericHostname); err != nil {
    panic(fmt.Sprintf("genericHostname constant %q is invalid: %v — this is a build bug", genericHostname, err))
  }
}

// Validate any hostname before passing to svchost.ForComparison.
func isValidSvchost(h string) bool {
  _, err := svchost.ForComparison(h)
  return err == nil
}

// This branch is documented unreachable; if reached, fail loudly with a bug report hint.
aliasHostname, err := svchost.ForComparison(genericHostname)
if err != nil {
  return nil, fmt.Errorf("BUG: static genericHostname %q failed validation (%w); "+
    "please report this to the Terraform backend maintainers", genericHostname, err)
}

When it happens

Trigger: svchost.ForComparison(genericHostname) at backend.go:207 returns an error. Because genericHostname is the hardcoded literal "localterraform.com" (a syntactically valid hostname), this branch is effectively unreachable in any correct build. The only way to hit it is if the constant is patched/overridden to an invalid hostname (empty string, underscores, disallowed chars, or >63-byte label), or svchost's validation rules change to reject it.

Common situations: A downstream fork or custom build modifies genericHostname to an invalid value; an svchost library upgrade tightens validation so the constant no longer parses; or test/mocking replaces the constant. End users on official builds will not see this.

Related errors

• failed to create backend alias to target
• invalid hostname in provider matching pattern
• a network issue prevented cloud configuration;
• a network issue prevented cloud configuration;
• address argument is required

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/d2ae3b45345169b3. Report an issue: GitHub.

Appendix: source

Thrown at internal/backend/remote/backend.go:210

	// Make sure that only one of workspace name or a prefix is configured.
	if name != "" && prefix != "" {
		diags = diags.Append(tfdiags.AttributeValue(
			tfdiags.Error,
			"Invalid workspaces configuration",
			`Only one of workspace "name" or "prefix" is allowed.`,
			cty.Path{cty.GetAttrStep{Name: "workspaces"}},
		))
	}

	return obj, diags
}

func (b *Remote) ServiceDiscoveryAliases() ([]backendrun.HostAlias, error) {
	aliasHostname, err := svchost.ForComparison(genericHostname)
	if err != nil {
		// This should never happen because the hostname is statically defined.
		return 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)
	}

	targetHostname, err := svchost.ForComparison(b.hostname)
	if err != nil {
		// This should never happen because the 'to' alias is the backend host, which has likely
		// already been evaluated as a svchost.Hostname by now
		return nil, fmt.Errorf("failed to create backend alias to target %q. The hostname is not in the correct format", b.hostname)
	}

	return []backendrun.HostAlias{
		{
			From: aliasHostname,
			To:   targetHostname,
		},
	}, nil
}

// Configure implements backend.Backend.

View on GitHub (pinned to d32a084675)