ipfs/kubo · error

%q is not an IPNS name

Error message

%q is not an IPNS name

What it means

KeyAPI(name.go).Search only resolves IPNS names. If the parsed path's namespace is not /ipns/ (e.g. /ipfs/ or /ipld/ immutable paths), Search rejects it with this error, since immutable content has nothing to search for.

Source

Thrown at core/coreapi/name.go:145

	// Accept a bare IPNS name (key or DNSLink), an /ipns/ path, or a native IPNS
	// URI (ipns://name, ipns:name).
	p, err := path.NewPathFromURI(name)
	if err != nil {
		// Wrap a bare name (no leading slash) as an /ipns/ path. Anything already
		// in path form that failed to parse keeps its original error rather than
		// being mangled by a second "/ipns/" prefix.
		if strings.HasPrefix(name, "/") {
			return nil, err
		}
		p, err = path.NewPath("/ipns/" + name)
		if err != nil {
			return nil, err
		}
	}
	// name resolution is IPNS-only; reject immutable /ipfs and /ipld inputs.
	if p.Namespace() != path.IPNSNamespace {
		return nil, fmt.Errorf("%q is not an IPNS name", name)
	}

	out := make(chan coreiface.IpnsResult)
	go func() {
		defer close(out)
		for res := range resolver.ResolveAsync(ctx, p, options.ResolveOpts...) {
			select {
			case out <- coreiface.IpnsResult{Path: res.Path, Err: res.Err}:
			case <-ctx.Done():
				return
			}
		}
	}()

	return out, nil
}

// Resolve attempts to resolve the newest version of the specified name and

View on GitHub (pinned to 329838acdf)

Solutions

1. Pass an IPNS name (k51... style name or /ipns/<name>) instead of an /ipfs/ path.
2. If you want the content of an immutable path, use the Unix filesystem/DAG API, not name Search.
3. Validate the namespace of user input before calling Search.

Example fix

// before
res, err := api.Name().Search(ctx, "/ipfs/bafybeig...")
// after
res, err := api.Name().Search(ctx, "/ipns/k51qzi5uqu5d...")

p, err := path.NewPath(name)
if err == nil && p.Namespace() != "/ipns" {
    return fmt.Errorf("Search requires an /ipns/ name, got %s", p.Namespace())
}

func isIPNSName(s string) bool {
    p, err := path.NewPath(s)
    return err == nil && p.Namespace() == path.IPNSNamespace
}

res, err := api.Name().Search(ctx, name)
if err != nil && strings.Contains(err.Error(), "is not an IPNS name") {
    return fmt.Errorf("%q must be an IPNS name, not content", name)
}

When it happens

Trigger: Calling KeyAPI.Search(ctx, name) with a path whose namespace is /ipfs/ or /ipld/, e.g. Search(ctx, "/ipfs/bafy...") or a bare CID parsed as an immutable path.

Common situations: Confusing name search with content lookup: passing a content CID instead of an IPNS name; passing a fully-qualified /ipfs/ gateway-style path.

Related errors

• %s key is not a map
• %s not found
• paths must not be empty
• paths must start with a leading slash
• cannot import key with name 'self'

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