ipfs/kubo · error

service endpoint should be provided without any query parame

Error message

service endpoint should be provided without any query parameters

What it means

After parsing the endpoint, `normalizeEndpoint` rejects URLs that carry query parameters (anything after `?`). Pinning service endpoints must be a bare base URL because the client appends its own PSA API paths; a query string would corrupt the composed request URLs.

Source

Thrown at core/commands/pin/remotepin.go:806

		return "", "", err
	}
	return endpoint, service.API.Key, nil
}

func normalizeEndpoint(endpoint string) (string, error) {
	uri, err := neturl.ParseRequestURI(endpoint)
	if err != nil || !(uri.Scheme == "http" || uri.Scheme == "https") {
		return "", fmt.Errorf("service endpoint must be a valid HTTP URL")
	}

	// cleanup trailing and duplicate slashes (https://github.com/ipfs/kubo/issues/7826)
	uri.Path = gopath.Clean(uri.Path)
	uri.Path = strings.TrimSuffix(uri.Path, ".")
	uri.Path = strings.TrimSuffix(uri.Path, "/")

	// remove any query params
	if uri.RawQuery != "" {
		return "", fmt.Errorf("service endpoint should be provided without any query parameters")
	}

	if strings.HasSuffix(uri.Path, "/pins") {
		return "", fmt.Errorf("service endpoint should be provided without the /pins suffix")
	}

	return uri.String(), nil
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Remove the query string and register only the base path: `https://api.example.com/psa`.
2. Pass the API key via the dedicated mechanism instead (`--key=<apikey>` on `ipfs pin remote add`), not as a query parameter.
3. Check the pinning service's docs for its exact PSA base endpoint URL (typically ends before any `/pins` path).
4. If the service only authenticates via query string, that is unsupported by kubo's remote pinning — ask the provider for a header-based key.

Example fix

// before
ipfs pin remote add svc https://api.example.com/psa?apikey=123 --key=$KEY
// after
ipfs pin remote add svc https://api.example.com/psa --key=$KEY

#!/usr/bin/env bash
EP="$2"
if [[ "$EP" == *\?* ]]; then
  echo "endpoint must not contain query parameters: ${EP%%\?*}" >&2
  EP="${EP%%\?*}"
fi
ipfs pin remote add "$1" "$EP" --key="$KEY"

When it happens

Trigger: Registering an endpoint like `https://api.example.com/psa?token=abc` or a URL copied from a browser address bar that included `?key=...` tracking/auth parameters.

Common situations: Users pasting URLs with API keys embedded as query params (an auth anti-pattern for PSA endpoints); browser-copied URLs with utm/track parameters; templated URLs that append `?format=json`.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• service endpoint must be a valid HTTP URL
• service endpoint should be provided without the /pins suffix
• remote pinning service name not specified
• unknowm mhType %d
• unknowm mhType %d

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/d0c0120d43061034. Report an issue: GitHub.