failed to create backend alias to target %q. The hostname is

Error message

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

What it means

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.

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

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.

Example fix

// before
terraform {
  backend "remote" {
    hostname = "app.terraform.io."  // trailing dot invalid
  }
}
// after
terraform {
  backend "remote" {
    hostname = "app.terraform.io"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate the user-supplied hostname before configuring the backend
import "github.com/hashicorp/terraform-svchost"

func validateHostname(h string) error {
  if _, err := svchost.ForComparison(h); err != nil {
    return fmt.Errorf("invalid backend hostname %q: %w", h, err)
  }
  return nil
}

// usage
if err := validateHostname(cfg.Hostname); err != nil { return err }

Try / catch

if _, err := b.ServiceDiscoveryAliases(); err != nil && strings.Contains(err.Error(), "hostname is not in the correct format") {
    // surface a clear 'fix your hostname attribute' message
}

Prevention

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.

When it happens

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

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

Related errors

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