hashicorp/terraform · error

invalid provider mirror base URL %s: %s

Error message

invalid provider mirror base URL %s: %s

What it means

mirrorHostCredentials() first derives a svchost.Hostname from the configured base URL via mirrorHost() -> svchostFromURL(), which runs IDNA normalization. If the host portion fails IDNA validation (RFC 5891) this error is returned, naming the base URL and the normalization error. It means the configured mirror URL has a hostname Terraform cannot treat as a service host.

Source

Thrown at internal/getproviders/http_mirror_source.go:304

//
// If the returned error is non-nil then the given hostname doesn't comply
// with the IETF RFC 5891 section 5.3 and 5.4 validation rules, and thus cannot
// be interpreted as a valid Terraform service host. The IDNA validation errors
// are unfortunately usually not very user-friendly, but they are also
// relatively rare because the IDNA normalization rules are quite tolerant.
func (s *HTTPMirrorSource) mirrorHost() (svchost.Hostname, error) {
	return svchostFromURL(s.baseURL)
}

// mirrorHostCredentials returns the HostCredentials, if any, for the hostname
// included in the mirror base URL.
//
// It might return an error if the mirror base URL is invalid, or if the
// credentials lookup itself fails.
func (s *HTTPMirrorSource) mirrorHostCredentials() (svcauth.HostCredentials, error) {
	hostname, err := s.mirrorHost()
	if err != nil {
		return nil, fmt.Errorf("invalid provider mirror base URL %s: %s", s.baseURL.String(), err)
	}

	if s.creds == nil {
		// No host-specific credentials, then.
		return nil, nil
	}

	return s.creds.ForHost(hostname)
}

// get is the shared functionality for querying a JSON index from a mirror.
//
// It only handles the raw HTTP request. The "body" return value is the
// reader from the response if and only if the response status code is 200 OK
// and the Content-Type is application/json. In all other cases it's nil.
// If body is non-nil then the caller must close it after reading it.
//
// If the "finalURL" return value is not empty then it's the URL that actually

View on GitHub (pinned to c9def3e214)

Solutions

1. Correct the hostname in the network_mirror URL to a valid DNS/IDNA name (letters, digits, hyphens).
2. Avoid underscores and other characters IDNA forbids in hostnames.
3. Re-enter the URL by hand rather than copy-pasting to drop stray characters.

Example fix

# before
provider_installation {
  network_mirror { url = "https://tf_mirror.local/" }  # underscore invalid
}

# after
provider_installation {
  network_mirror { url = "https://tf-mirror.local/" }
}

// Validate a configured mirror URL up front.
if _, err := svchost.ForCompatibility(strings.SplitN(u.Host, ":", 2)[0]); err != nil {
    return fmt.Errorf("mirror hostname invalid: %w", err)
}

When it happens

Trigger: The base URL host contains invalid characters, invalid punycode, or otherwise fails idna.Display.ToUnicode / svchost.ForComparison. Triggered when credentials are being attached to a request (so typically when a creds source is configured).

Common situations: Typo in the mirror URL (e.g. underscore in hostname, which IDNA rejects); a URL with a port that normalizes oddly; copy-pasted URL with stray characters.

Related errors

• failed to determine request credentials: %s
• invalid credentials for %s
• Invalid URL: %v must be: %v
• provider mirror returned invalid URL %q: %s
• invalid hostname in provider matching pattern %q: %s

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