What causes "registry response includes invalid download URL: %s" in hashicorp/terraform?

Fetch the raw download response and inspect download_url for invalid characters or encoding.

registry response includes invalid download URL: %s

Error message

registry response includes invalid download URL: %s

What it means

PackageMeta could not url.Parse the download_url field from the registry response, so there is no valid URL to fetch the provider archive from. The download is aborted before any network fetch with a plain fmt.Errorf wrapping the parse error.

Source

Thrown at internal/getproviders/registry_client.go:285

		if !match {
			// If the protocol version is not supported, try to find the closest
			// matching version.
			closest, err := c.findClosestProtocolCompatibleVersion(ctx, provider, version)
			if err != nil {
				return PackageMeta{}, err
			}
			protoErr.Suggestion = closest
			return PackageMeta{}, protoErr
		}
	}

	if body.OS != target.OS || body.Arch != target.Arch {
		return PackageMeta{}, fmt.Errorf("registry response to request for %s archive has incorrect target %s", target, Platform{body.OS, body.Arch})
	}

	downloadURL, err := url.Parse(body.DownloadURL)
	if err != nil {
		return PackageMeta{}, fmt.Errorf("registry response includes invalid download URL: %s", err)
	}
	downloadURL = resp.Request.URL.ResolveReference(downloadURL)
	if downloadURL.Scheme != "http" && downloadURL.Scheme != "https" {
		return PackageMeta{}, fmt.Errorf("registry response includes invalid download URL: must use http or https scheme")
	}

	ret := PackageMeta{
		Provider:         provider,
		Version:          version,
		ProtocolVersions: protoVersions,
		TargetPlatform: Platform{
			OS:   body.OS,
			Arch: body.Arch,
		},
		Filename: body.Filename,
		Location: PackageHTTPURL(downloadURL.String()),
		// "Authentication" is populated below
	}

View on GitHub (pinned to c9def3e214)

Solutions

Fetch the raw download response and inspect download_url for invalid characters or encoding.
Fix the registry to emit a well-formed absolute or relative URL (relative is resolved against the request URL).
URL-encode any dynamic path segments the registry injects.

Example fix

// before
{"download_url":"https://reg/p/terraform-provider v1.0.zip"}
// after
{"download_url":"https://reg/p/terraform-provider%20v1.0.zip"}

Defensive patterns

Strategy: try-catch

Try / catch

meta, err := client.PackageMeta(ctx, provider, ver, plat)
if err != nil {
    if strings.Contains(err.Error(), "invalid download URL") && !strings.Contains(err.Error(), "scheme") {
        // registry returned a malformed download_url; not retryable, report upstream
    }
    return err
}

Prevention

For private registries, lint the download_url with url.Parse in a test fixture.
URL-encode dynamic segments the registry injects into the URL.
Return absolute https URLs to avoid resolution ambiguity.

When it happens

Trigger: Registry response's download_url contains characters or structure that Go's url.Parse rejects (control chars, invalid percent-encoding, missing scheme with a colon in the wrong place).

Common situations: Custom registry templating bug producing a broken URL; a space or stray quote in the URL; URL built by string concatenation with an unencoded segment; registry returned an empty download_url combined with other bad characters.

Related errors

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