invalid provider matching pattern %q: must have either two o

Error message

invalid provider matching pattern %q: must have either two or three slash-separated segments

What it means

ParseMultiSourceMatchingPatterns splits each pattern on '/' and requires exactly two or three segments. Fewer than two or more than three segments yields this error. Patterns are "namespace/type" or "hostname/namespace/type"; a bare "aws" or "a/b/c/d" is invalid.

Source

Thrown at internal/getproviders/multi_source.go:151

// The Provider address values in a MultiSourceMatchingPatterns are special in
// that any of Hostname, Namespace, or Type can be getproviders.Wildcard
// to indicate that any concrete value is permitted for that segment.
type MultiSourceMatchingPatterns []addrs.Provider

// ParseMultiSourceMatchingPatterns parses a slice of strings containing the
// string form of provider matching patterns and, if all the given strings are
// valid, returns the corresponding, normalized, MultiSourceMatchingPatterns
// value.
func ParseMultiSourceMatchingPatterns(strs []string) (MultiSourceMatchingPatterns, error) {
	if len(strs) == 0 {
		return nil, nil
	}

	ret := make(MultiSourceMatchingPatterns, len(strs))
	for i, str := range strs {
		parts := strings.Split(str, "/")
		if len(parts) < 2 || len(parts) > 3 {
			return nil, fmt.Errorf("invalid provider matching pattern %q: must have either two or three slash-separated segments", str)
		}
		host := defaultRegistryHost
		explicitHost := len(parts) == 3
		if explicitHost {
			givenHost := parts[0]
			if givenHost == "*" {
				host = svchost.Hostname(Wildcard)
			} else {
				normalHost, err := svchost.ForComparison(givenHost)
				if err != nil {
					return nil, fmt.Errorf("invalid hostname in provider matching pattern %q: %s", str, err)
				}

				// The remaining code below deals only with the namespace/type portions.
				host = normalHost
			}

			parts = parts[1:]

View on GitHub (pinned to c9def3e214)

Solutions

Write the pattern as "namespace/type" or "hostname/namespace/type".
Remove stray leading/trailing slashes and empty segments.
Use the default-registry short form ("hashicorp/aws") when you mean registry.terraform.io.

Example fix

# before
provider_installation {
  network_mirror { url = "https://m/tf/" include = ["aws"] }
}

# after
provider_installation {
  network_mirror { url = "https://m/tf/" include = ["hashicorp/aws"] }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate segment count before parsing patterns.
parts := strings.Split(p, "/")
if len(parts) < 2 || len(parts) > 3 {
    return fmt.Errorf("pattern %q must have 2 or 3 slash-separated segments", p)
}

Prevention

Use the "namespace/type" or "hostname/namespace/type" shape only.
Lint provider_installation include/exclude patterns in CI.
Avoid trailing slashes that create empty segments.

When it happens

Trigger: Passing a string with the wrong number of slash-separated parts, e.g. "aws" (one segment), "hashicorp/aws/extra/here" (four), or an empty string. Triggered at config load when include/exclude patterns for a provider_installation block are parsed.

Common situations: Typing a provider source address without the namespace ("aws" instead of "hashicorp/aws"); extra trailing slash creating an empty segment; copy-paste of a full provider FQN with a registry path appended.

Related errors

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