What causes "service not known" in ipfs/kubo?

Register the service first: `ipfs pin remote add --key= ` (service-add command), then retry.

service not known

Error message

service not known

What it means

`getRemotePinServiceInfo` looks up endpoint and API key for a service name in `Pinning.RemoteServices`. When the config map itself is nil (no remote services have ever been configured on this node), it cannot resolve the name and returns `service not known`. This is the nil-map branch of the same lookup that also fails when the map exists but lacks the name (see error 425).

Source

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

	return pinclient.NewClient(endpoint, key), nil
}

func getRemotePinServiceInfo(env cmds.Environment, name string) (endpoint, key string, err error) {
	cfgRoot, err := cmdenv.GetConfigRoot(env)
	if err != nil {
		return "", "", err
	}
	repo, err := fsrepo.Open(cfgRoot)
	if err != nil {
		return "", "", err
	}
	defer repo.Close()
	cfg, err := repo.Config()
	if err != nil {
		return "", "", err
	}
	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")
	}

View on GitHub (pinned to 329838acdf)

Solutions

Register the service first: `ipfs pin remote add <name> <endpoint> --key=<apikey>` (service-add command), then retry.
Verify you are operating on the right repo: check `$IPFS_PATH` and confirm the service exists via `ipfs config Pinning.RemoteServices --json`.
If the config was wiped, re-add all services from your provisioning scripts/backups.
Inspect `~/.ipfs/config` (or `$IPFS_PATH/config`) directly to confirm the `Pinning.RemoteServices` key exists.

Example fix

// before
ipfs pin remote ls --service=pinata   # node has no services configured
// after
ipfs pin remote add pinata https://api.pinata.cloud/psa --key=$PINATA_JWT
ipfs pin remote ls --service=pinata

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
# ensure the repo has any remote services configured
if ! ipfs config Pinning.RemoteServices --json 2>/dev/null | grep -q 'Pinata\|web3\| Filebase\|storage'; then
  echo "no remote pinning services configured; run 'ipfs pin remote add ...' first" >&2
  exit 1
fi

Prevention

Register services as part of node init/provisioning before using pin remote
Confirm IPFS_PATH points at the repo where services were configured
Back up the config section so wiped configs can be restored

When it happens

Trigger: Any `pin remote` operation referencing a service via `--service=<name>` on a node where `Pinning.RemoteServices` is nil — i.e. the service was never added with `ipfs pin remote add` (service registration) and no services exist in the config at all.

Common situations: Fresh node or fresh IPFS_PATH where the service setup step was skipped; pointing the CLI at the wrong repo (wrong IPFS_PATH) that has no services configured; config migration/reset wiped Pinning.RemoteServices.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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