What causes "provider mirror returned invalid URL %q: %s" in hashicorp/terraform?

Inspect the version JSON and the failing archive entry's "url" value.

provider mirror returned invalid URL %q: %s

Error message

provider mirror returned invalid URL %q: %s

What it means

Each archive entry in the version JSON carries a "url" field (RelativeURL). The code url.Parse()s it to resolve against the final request URL; if parsing fails the query is failed via errQueryFailed with this message, quoting the offending URL and the parse error. It signals a malformed archive URL in the mirror's response.

Source

Thrown at internal/getproviders/http_mirror_source.go:224

	if err := dec.Decode(&bodyContent); err != nil {
		return PackageMeta{}, s.errQueryFailed(provider, fmt.Errorf("invalid response content from mirror server: %s", err))
	}

	archiveMeta, ok := bodyContent.Archives[target.String()]
	if !ok {
		return PackageMeta{}, ErrPlatformNotSupported{
			Provider:  provider,
			Version:   version,
			Platform:  target,
			MirrorURL: s.baseURL,
		}
	}

	relURL, err := url.Parse(archiveMeta.RelativeURL)
	if err != nil {
		return PackageMeta{}, s.errQueryFailed(
			provider,
			fmt.Errorf("provider mirror returned invalid URL %q: %s", archiveMeta.RelativeURL, err),
		)
	}
	absURL := finalURL.ResolveReference(relURL)

	ret := PackageMeta{
		Provider:       provider,
		Version:        version,
		TargetPlatform: target,

		Location: PackageHTTPURL(absURL.String()),
		Filename: path.Base(absURL.Path),
	}
	// A network mirror might not provide any hashes at all, in which case
	// the package has no source-defined authentication whatsoever.
	if len(archiveMeta.Hashes) > 0 {
		hashes := make([]Hash, 0, len(archiveMeta.Hashes))
		for _, hashStr := range archiveMeta.Hashes {
			hash, err := ParseHash(hashStr)

View on GitHub (pinned to c9def3e214)

Solutions

Inspect the version JSON and the failing archive entry's "url" value.
Ensure the mirror percent-encodes any reserved/space characters in archive URLs.
Regenerate the version file with valid URL references.

Example fix

# before: bad url in version json
{"archives":{"linux_amd64":{"url":"../aws 5.2.0.zip"}}}

# after: percent-encoded
{"archives":{"linux_amd64":{"url":"../aws%205.2.0.zip"}}}

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate archive URLs parse before publishing a mirror.
if _, err := url.Parse(entry.RelativeURL); err != nil {
    return fmt.Errorf("archive url %q invalid: %w", entry.RelativeURL, err)
}

Try / catch

var qf getproviders.ErrQueryFailed
if errors.As(err, &qf) && strings.Contains(qf.Error(), "invalid URL") {
    // mirror published a bad archive url; surface to operator
}

Prevention

Percent-encode spaces and reserved characters in archive filenames.
url.Parse-check every archive URL during mirror generation.
Avoid hand-editing version JSON.

When it happens

Trigger: An archive entry's "url" field contains characters that are illegal in a URL reference (raw spaces, control chars, unencoded non-ASCII), or an invalid escape. The mirror published a bad relative/absolute URL.

Common situations: Mirror generator forgot to URL-encode filenames; a filename with spaces or special characters; hand-edited JSON with a typo.

Related errors

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