What causes "service endpoint must be a valid HTTP URL" in ipfs/kubo?

Prefix the endpoint with its scheme: use `https://api.pinata.cloud/psa` instead of `api.pinata.cloud/psa`.

service endpoint must be a valid HTTP URL

Error message

service endpoint must be a valid HTTP URL

What it means

`normalizeEndpoint` validates a remote pinning service endpoint before storing/using it. It parses the URL with `url.ParseRequestURI` and requires the scheme to be http or https. Anything unparseable, schemeless (e.g. `api.pinata.cloud` with no `https://`), or using another scheme (ftp:, file:) produces this error.

Source

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

	}
	if cfg.Pinning.RemoteServices == nil {
		return "", "", fmt.Errorf("service not known")
	}
	service, present := cfg.Pinning.RemoteServices[name]
	if !present {
		return "", "", fmt.Errorf("service not known")
	}
	endpoint, err = normalizeEndpoint(service.API.Endpoint)
	if err != nil {
		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

Prefix the endpoint with its scheme: use `https://api.pinata.cloud/psa` instead of `api.pinata.cloud/psa`.
Check for typos in the scheme (`http://`, `https://`) and stray whitespace/characters; re-type the URL cleanly.
Ensure the whole URL is quoted in the shell if it contains `&` or `?` characters: `ipfs pin remote add name "https://..." --key=...`.
Validate locally: `go`-style check or simply confirm the URL opens in a browser before registering.

Example fix

// before
ipfs pin remote add pinata api.pinata.cloud/psa --key=$KEY
// after
ipfs pin remote add pinata https://api.pinata.cloud/psa --key=$KEY

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
EP="$2"
if [[ "$EP" != http://* && "$EP" != https://* ]]; then
  echo "endpoint must start with http:// or https://" >&2
  exit 1
fi
ipfs pin remote add "$1" "$EP" --key="$KEY"

Prevention

Always include the scheme when copying endpoint URLs
Quote URLs in shell to avoid stray characters
Test the URL in a browser or with curl before registering

When it happens

Trigger: `ipfs pin remote add <name> <endpoint>` (or config edit + use) where the endpoint lacks a scheme (`ipfs pin remote add pinata api.pinata.cloud/psa`), contains invalid URL characters, or uses a non-HTTP scheme.

Common situations: Omitting `https://` when copying a bare hostname from docs; trailing spaces or invisible characters in the endpoint from copy-paste; typos like `htp://` or `https:/` (single slash).

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

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