hasura/graphql-engine · error

unable to parse uri: %w

Error message

unable to parse uri: %w

What it means

downloadAndExtract parses the platform's download URI with url.Parse before choosing a fetcher (file:// uses NewFileFetcher, otherwise a network fetcher). If url.Parse returns an error the URI is unusable and the failure is wrapped. This runs during installPlugin, after validation.

Source

Thrown at cli/plugins/util.go:150

	for _, platform := range platforms {
		if platform.Selector == currSelector {
			return platform, true, nil
		}
	}

	return Platform{}, false, nil
}

// downloadAndExtract downloads the specified archive uri (or uses the provided overrideFile, if a non-empty value)
// while validating its checksum with the provided sha256sum, and extracts its contents to extractDir that must be.
// created.
func downloadAndExtract(extractDir, uri, sha256sum string) error {
	var op errors.Op = "plugins.downloadAndExtract"

	nurl, err := url.Parse(uri)
	if err != nil {
		return errors.E(op, fmt.Errorf("unable to parse uri: %w", err))
	}

	var fetcher download.Fetcher
	if nurl.Scheme == "file" {
		fetcher = download.NewFileFetcher(nurl.Path)
	} else {
		fetcher = download.HTTPFetcher{}
	}

	verifier := download.NewSha256Verifier(sha256sum)

	err = download.NewDownloader(verifier, fetcher).Get(uri, extractDir)
	if err != nil {
		return errors.E(op, fmt.Errorf("failed to unpack the plugin archive: %w", err))
	}

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Fix the URI in the manifest: ensure valid percent-encoding and no stray whitespace/control characters.
2. Build URLs programmatically with net/url (url.Parse + Query/Set) instead of string concatenation.
3. Test with url.Parse(uri) locally before publishing the manifest.

Example fix

// before
"url": "https://example.com/rele ases/my plugin.tar.gz"

// after
"url": "https://example.com/releases/my-plugin.tar.gz"

if _, err := url.Parse(uri); err != nil {
	return fmt.Errorf("bad uri in manifest: %w", err)
}

func isParsableURI(uri string) bool {
	_, err := url.Parse(uri)
	return err == nil
}

When it happens

Trigger: installPlugin → downloadAndExtract receiving a URI with invalid percent-encoding (e.g. "%zz"), control characters, or otherwise malformed URL syntax that Go's url.Parse rejects.

Common situations: Unescaped spaces or % characters in the release URL, URLs assembled via string concatenation without url.PathEscape, or trailing whitespace/newlines pasted into the manifest.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• install failed: %w
• failed to unpack into staging dir: %w
• failed to unpack the plugin archive: %w
• cannot create metadata files: %w
• parsing yaml metadata to json: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/5cf17490d72a874a. Report an issue: GitHub.