hashicorp/terraform · critical

failed to create backend alias from alias %q. The hostname i

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

Returned by Remote.ServiceDiscoveryAliases when svchost.ForComparison(genericHostname) fails for the statically-defined generic hostname constant. The code comment explicitly states this should never happen — it is a defensive check against an invalid built-in constant, so encountering it indicates a bug in the Terraform build itself rather than user configuration.

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 c9def3e214)

Solutions

1. Report a bug — this path is unreachable with the official genericHostname constant.
2. If running a fork, verify the genericHostname constant is a valid RFC-1123 hostname (e.g. 'app.terraform.io').
3. Rebuild from a clean checkout of the official source.
4. Confirm the binary is not corrupted (checksums).

Example fix

// before: custom build set genericHostname = ""
// after
const genericHostname = "app.terraform.io"

// Validate the built-in constant at startup (defensive, since it should be unreachable)
func validateGenericHostname() error {
  if _, err := svchost.ForComparison(genericHostname); err != nil {
    return fmt.Errorf("build is corrupt: genericHostname %q invalid: %w", genericHostname, err)
  }
  return nil
}

// This is a bug path; surface it loudly rather than recovering
if _, err := b.ServiceDiscoveryAliases(); err != nil && strings.Contains(err.Error(), "bug in the backend") {
    panic(fmt.Errorf("unreachable: %w", err)) // file an issue
}

When it happens

Trigger: ServiceDiscoveryAliases() is invoked during backend host aliasing; svchost.ForComparison rejects the genericHostname constant because it is empty, too long, or otherwise RFC-compliance-violating. This requires the compiled-in constant to be malformed.

Common situations: A custom/forked Terraform build that changed genericHostname to an invalid value; an extremely old or corrupted binary; practically never seen in official releases.

Related errors

• failed to create backend alias to target %q. The hostname is
• No state data received from Terraform: No state data was rec
• organization %q at host %s not found. Please ensure that th
• a network issue prevented cloud configuration; %w
• a network issue prevented cloud configuration; %w

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