Name.Resolve: depth other than 1 or %d not supported

Error message

Name.Resolve: depth other than 1 or %d not supported

What it means

The RPC client's name Search path only supports resolving at depth 1 (non-recursive) or DefaultDepthLimit (-1, unlimited); any other depth is rejected because name/resolve over HTTP only exposes the recursive toggle, not intermediate depths.

Source

Thrown at client/rpc/name.go:54

		req.Option("ttl", options.TTL)
	}

	var out ipnsEntry
	if err := req.Exec(ctx, &out); err != nil {
		return ipns.Name{}, err
	}
	return ipns.NameFromString(out.Name)
}

func (api *NameAPI) Search(ctx context.Context, name string, opts ...caopts.NameResolveOption) (<-chan iface.IpnsResult, error) {
	options, err := caopts.NameResolveOptions(opts...)
	if err != nil {
		return nil, err
	}

	ropts := namesys.ProcessResolveOptions(options.ResolveOpts)
	if ropts.Depth != namesys.DefaultDepthLimit && ropts.Depth != 1 {
		return nil, fmt.Errorf("Name.Resolve: depth other than 1 or %d not supported", namesys.DefaultDepthLimit)
	}

	req := api.core().Request("name/resolve", name).
		Option("nocache", !options.Cache).
		Option("recursive", ropts.Depth != 1).
		Option("dht-record-count", ropts.DhtRecordCount).
		Option("dht-timeout", ropts.DhtTimeout).
		Option("stream", true)
	resp, err := req.Send(ctx)
	if err != nil {
		return nil, err
	}
	if resp.Error != nil {
		return nil, resp.Error
	}

	res := make(chan iface.IpnsResult)

View on GitHub (pinned to 329838acdf)

Solutions

Use Depth: 1 for a single resolution step or namesys.DefaultDepthLimit (-1) for full recursion; drop the Depth option to get the default.
If you genuinely need intermediate depth, resolve fully (depth -1) and walk the returned path segments yourself.
Run a local daemon lookup with `ipfs name resolve --dht-record-count ... -d N` via exec if intermediate depth is a hard requirement.

Example fix

// before
p, err := api.Name().Resolve(ctx, name, options.Name.AllowOffline(false))
// opts had ResolveOpts{Depth: 2}
// after
ropts := options.ResolveOpts{Depth: namesys.DefaultDepthLimit} // or 1
p, err := api.Name().Resolve(ctx, name, options.Name.AllowOffline(false))

Defensive patterns

Strategy: validation

Validate before calling

d := optsDepth // your configured depth
if d != 1 && d != namesys.DefaultDepthLimit {
    d = namesys.DefaultDepthLimit // clamp to a supported value before calling
}

Prevention

Only use Depth 1 or namesys.DefaultDepthLimit with the HTTP client
Centralize ResolveOpts construction so arbitrary depths never reach Resolve
Resolve recursively and truncate paths locally if bounded depth is needed

When it happens

Trigger: Calling api.Name().Search(ctx, name, options.Name.ResolveOption(...)...) — via Resolve with depth>1 — after constructing options.ResolveOpts{Depth: n} where n is neither 1 nor -1 (e.g. Depth: 2 or 3 for 'resolve two hops').

Common situations: Developers translating the local namesys API (which supports arbitrary depths) to the HTTP client and picking a bounded depth like 2; porting code that used ipfs name resolve -d 2 locally.

Related errors

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