hashicorp/terraform · error

failed to create backend alias to target

Error message

failed to create backend alias to target %q. The hostname is not in the correct format

What it means

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.

Solutions

1. Verify the configured hostname in the backend 'host'/'address' block is a plain lowercase RFC-1123 host (no scheme, port, underscore, or trailing dot).
2. Re-run 'terraform init' to force service discovery to re-validate and overwrite b.hostname.
3. If you build/embed Terraform, audit any code path that sets b.hostname without going through svchost.ForComparison first.
4. Report as a bug: the comment itself states this should never happen, so a real occurrence indicates a broken invariant worth filing upstream.

Example fix

// before: raw user host assigned directly
b.hostname = cfg.Host
// after: validate via svchost before storing
h, err := svchost.ForComparison(cfg.Host)
if err != nil {
    return fmt.Errorf("invalid hostname %q: %w", cfg.Host, err)
}
b.hostname = h.String()

// Validate the hostname is a parseable svchost before storing/using it.
import "github.com/hashicorp/terraform-svchost"

func validateBackendHostname(raw string) error {
    if _, err := svchost.ForComparison(raw); err != nil {
        return fmt.Errorf("hostname %q is not valid: %w", raw, err)
    }
    return nil
}

// call during backend config validation, before ServiceDiscoveryAliases()

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error asking
• Error creating workspace
• error finding remote workspace
• error loading state
• failed to create backend alias from alias

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

Appendix: source

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

			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.
func (b *Remote) Configure(obj cty.Value) tfdiags.Diagnostics {
	var diags tfdiags.Diagnostics
	if obj.IsNull() {
		return diags
	}

	// Get the hostname.

View on GitHub (pinned to d32a084675)