What causes "The host %q block has an invalid hostname: %s" in hashicorp/terraform?

Use a bare hostname without scheme, path, or port, e.g. `host "example.com"`.

The host %q block has an invalid hostname: %s

Error message

The host %q block has an invalid hostname: %s

What it means

Emitted by `Config.Validate` (cliconfig.go:294-300) when a `host` block's label fails `svchost.ForComparison`. That function normalizes/validates a hostname per RFC 952/IDNA rules; an error means the label is not a usable service hostname. The `%s` values are the offending host label and the svchost error.

Source

Thrown at internal/command/cliconfig/cliconfig.go:298

// method. A non-nil diagnostics is not necessarily an error, since it may
// contain just warnings.
func (c *Config) Validate() tfdiags.Diagnostics {
	var diags tfdiags.Diagnostics

	if c == nil {
		return diags
	}

	// FIXME: Right now our config parsing doesn't retain enough information
	// to give proper source references to any errors. We should improve
	// on this when we change the CLI config parser to use HCL2.

	// Check that all "host" blocks have valid hostnames.
	for givenHost := range c.Hosts {
		_, err := svchost.ForComparison(givenHost)
		if err != nil {
			diags = diags.Append(
				fmt.Errorf("The host %q block has an invalid hostname: %s", givenHost, err),
			)
		}
	}

	// Check that all "credentials" blocks have valid hostnames.
	for givenHost := range c.Credentials {
		_, err := svchost.ForComparison(givenHost)
		if err != nil {
			diags = diags.Append(
				fmt.Errorf("The credentials %q block has an invalid hostname: %s", givenHost, err),
			)
		}
	}

	// Should have zero or one "credentials_helper" blocks
	if len(c.CredentialsHelpers) > 1 {
		diags = diags.Append(
			fmt.Errorf("No more than one credentials_helper block may be specified"),

View on GitHub (pinned to c9def3e214)

Solutions

Use a bare hostname without scheme, path, or port, e.g. `host "example.com"`.
Remove underscores and other illegal hostname characters from the label.
For local/private hosts, use a resolvable DNS name or a simple dotted name.
Re-run `terraform init`; `Validate` runs on every config load.

Example fix

# before
host "https://registry.example.com" {
  services = { ... }
}
# The host "https://registry.example.com" block has an invalid hostname: ...

# after
host "registry.example.com" {
  services = { ... }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate host labels with the same normalizer Terraform uses.
import svchost "github.com/hashicorp/terraform-svchost"

func hostLabelOK(label string) error {
    if _, err := svchost.ForComparison(label); err != nil {
        return fmt.Errorf("invalid host %q: %w", label, err)
    }
    return nil
}

Prevention

Use bare hostnames without scheme, path, or port in `host` blocks.
Avoid underscores and illegal characters in host labels.
Validate IDN hostnames convert to punycode before saving.

When it happens

Trigger: A `host "..." { }` block in `.terraformrc` with an invalid hostname: contains underscores, spaces, empty labels, trailing dots, or invalid IDNA characters.

Common situations: Using `host "_internal"` (underscore illegal in hostnames); pasting a URL instead of a host (`host "https://x"`); IDN names that fail punycode conversion; a stray space or typo.

Related errors

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