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

Set the label to the bare registry host, e.g. `credentials "app.terraform.io" { token = "..." }`.

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

Error message

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

What it means

Emitted by `Config.Validate` (cliconfig.go:304-310) when a `credentials` block's label fails `svchost.ForComparison`. Same hostname rules as error 549 but applied to the `credentials "<host>" { token = ... }` block. The `%s` values are the host label and the svchost error.

Source

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

	// 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"),
		)
	}

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

View on GitHub (pinned to c9def3e214)

Solutions

Set the label to the bare registry host, e.g. `credentials "app.terraform.io" { token = "..." }`.
Strip scheme/path/port from the label.
For tokens keyed by host, prefer the `TF_TOKEN_<host>` environment variable if the label is awkward (dots→underscores).
Validate the hostname normalizes under svchost before saving.

Example fix

# before
credentials "https://app.terraform.io" {
  token = "atlasv1..."
}
# The credentials "https://app.terraform.io" block has an invalid hostname: ...

# after
credentials "app.terraform.io" {
  token = "atlasv1..."
}

Defensive patterns

Strategy: validation

Validate before calling

// Reuse the svchost validator for credentials block labels.
import svchost "github.com/hashicorp/terraform-svchost"

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

Prevention

Label `credentials` blocks with the bare registry hostname.
For tricky hostnames, use `TF_TOKEN_<host>` instead (dots→underscores).
Strip scheme/path/port from labels.

When it happens

Trigger: A `credentials "..." { }` block whose label is not a valid service hostname (underscores, scheme prefix, spaces, empty/oversized labels).

Common situations: `credentials "_vault" { ... }`; pasting a full URL as the host; mis-typed hostname with a space; an IDN that fails conversion.

Related errors

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