ipfs/kubo · error

unsupported path namespace: %s

Error message

unsupported path namespace: %s

What it means

ResolvePath only knows two path namespaces: IPLD (/ipld/) and IPFS (/ipfs/, which resolves via the UnixFS resolver). Any other namespace on the passed path — /ipns/, /dag/, /p2p/ or a malformed path — is rejected with this error naming the unsupported namespace.

Source

Thrown at core/coreapi/path.go:59

	ctx, span := tracing.Span(ctx, "CoreAPI", "ResolvePath", trace.WithAttributes(attribute.String("path", p.String())))
	defer span.End()

	res, err := namesys.Resolve(ctx, api.namesys, p)
	if errors.Is(err, namesys.ErrNoNamesys) {
		return path.ImmutablePath{}, nil, coreiface.ErrOffline
	} else if err != nil {
		return path.ImmutablePath{}, nil, err
	}
	p = res.Path

	var resolver ipfspathresolver.Resolver
	switch p.Namespace() {
	case path.IPLDNamespace:
		resolver = api.ipldPathResolver
	case path.IPFSNamespace:
		resolver = api.unixFSPathResolver
	default:
		return path.ImmutablePath{}, nil, fmt.Errorf("unsupported path namespace: %s", p.Namespace())
	}

	imPath, err := path.NewImmutablePath(p)
	if err != nil {
		return path.ImmutablePath{}, nil, err
	}

	node, remainder, err := resolver.ResolveToLastNode(ctx, imPath)
	if err != nil {
		return path.ImmutablePath{}, nil, err
	}

	segments := []string{p.Namespace(), node.String()}
	segments = append(segments, remainder...)

	p, err = path.NewPathFromSegments(segments...)
	if err != nil {
		return path.ImmutablePath{}, nil, err

View on GitHub (pinned to 329838acdf)

Solutions

1. Resolve IPNS names first (e.g. coreapi ResolveNode on /ipns/ or 'ipfs name resolve') then pin the resulting /ipfs/ path
2. Use /ipld/ or /ipfs/ prefixed paths as appropriate
3. Verify the path string starts with /ipfs/ or /ipld/ before calling

Example fix

// before
api.Pin().Add(ctx, path.New("/ipns/my-domain.com"))
// after
p, _ := api.Unixfs().ResolvePath? -> resolve via name first
resolved, _ := api.ResolveNode(ctx, path.New("/ipns/my-domain.com"))
api.Pin().Add(ctx, path.FromCid(resolved.Cid()))

p := path.New(pstring)
ns := p.Namespace()
if ns != path.IPFSNamespace && ns != path.IPLDNamespace {
    // resolve /ipns/ names first or reject the input
}

func isResolvableCoreAPIPath(p path.Path) bool {
	ns := p.Namespace()
	return ns == path.IPFSNamespace || ns == path.IPLDNamespace
}

When it happens

Trigger: Passing an /ipns/... path, a /dag/... path, or a bare CID/path that fails namespace detection to ResolvePath (indirectly from pin add, pin ls, cat/get via ResolveNode, objectsForPaths).

Common situations: Pinning an IPNS name directly instead of resolving it first; passing 'dag' RPC-style CIDs into the CoreAPI pin API; older code paths using /ipns/ with the pin API.

Related errors

• %q is not an IPNS name
• could not resolve name
• Name.Resolve: depth other than 1 or %d not supported
• %s key is not a map
• %s not found

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