hashicorp/terraform · error

The host block has an invalid hostname

Error message

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

What it means

Thrown during CLI config validation when a host block contains a hostname that fails svchost.ForComparison normalization. Hostnames must be valid, normalizable DNS names for Terraform to use them for service discovery and credential matching. The error includes the offending hostname and the underlying validation error.

Solutions

1. Correct the hostname to be a valid DNS name (letters, digits, hyphens, and dots only)
2. Remove underscores, trailing dots, spaces, or special characters
3. Verify the hostname resolves: nslookup <hostname> or dig <hostname>
4. Check for invisible/whitespace characters in the config file

Example fix

// before
host "app_terraform_io" {
  services = {}
}

// after
host "app.terraform.io" {
  services = {}
}

// Validate hostname before using in a host block
func validateHostname(h string) error {
    _, err := svchost.ForComparison(h)
    return err
}

// Simple DNS-safe check without the svchost dependency
func isValidHostname(h string) bool {
    if h == "" || len(h) > 253 {
        return false
    }
    matched, _ := regexp.MatchString(`^[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?$`, h)
    return matched && !strings.Contains(h, "_")
}

When it happens

Trigger: For each key in c.Hosts, svchost.ForComparison(givenHost) returns an error. This happens when the hostname contains invalid characters (underscores, spaces), has an invalid format (trailing dots, empty labels), or is empty.

Common situations: Typo in hostname (e.g., app.terraform..io with double dots); using underscores which DNS forbids; hostname from a variable that resolved incorrectly; copy-paste with trailing whitespace or invisible characters.

Related errors

• The credentials block has an invalid hostname
• invalid hostname in provider matching pattern
• invalid provider matching pattern
• No more than one credentials_helper block may be specified
• No more than one provider_installation block may be…

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

Appendix: 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 d32a084675)