ipfs/kubo · error

error constructing namesys

Error message

error constructing namesys: %w

What it means

Offline IPNS name resolution requires constructing a namesys.NameSystem over the offline routing (datastore-backed value store). If namesys.NewNameSystem fails with any of the supplied options, coreapi wraps the underlying cause with this message so the construction failure is attributed to namesys.

Solutions

1. Inspect the wrapped %w cause to identify the actual namesys failure (datastore, resolver, or cache option).
2. Verify the repo datastore opens and is writable before constructing the offline node.
3. Ensure the provided dnsResolver is a non-nil, functional resolver.
4. Simplify to default options (only WithDatastore/WithDNSResolver) and add options back incrementally.

if settings.Offline {
    if api.repo.Datastore() == nil {
        return errors.New("offline mode requires an open repo datastore")
    }
    if dnsResolver == nil {
        return errors.New("offline mode requires a DNS resolver")
}
}

subAPI.namesys, err = namesys.NewNameSystem(routing, nsOptions...)
if err != nil {
    return nil, fmt.Errorf("error constructing namesys: %w", err) // inspect cause with errors.As/Is
}

When it happens

Trigger: Calling coreapi.NewNode with APIOptions{Offline: true} where the resulting namesys options (WithDatastore, WithDNSResolver, WithCache) or the offline router cause namesys.NewNameSystem to return an error, e.g. an invalid resolver or incompatible datastore.

Common situations: Injecting a custom DNS resolver that is nil or misconfigured; constructing an offline API node over a repo whose datastore failed mid-init; supplying a namesys option combination that namesys rejects.

Related errors

• error constructing namesys
• can't put while offline: pass `--allow-offline` to store…
• cannot specify negative resolve cache size
• could not resolve name
• %s : %w

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

Appendix: source

Thrown at core/coreapi/coreapi.go:239

		if cs == 0 {
			cs = node.DefaultIpnsCacheSize
		}
		if cs < 0 {
			return nil, errors.New("cannot specify negative resolve cache size")
		}

		nsOptions := []namesys.Option{
			namesys.WithDatastore(subAPI.repo.Datastore()),
			namesys.WithDNSResolver(subAPI.dnsResolver),
			namesys.WithCache(cs),
			namesys.WithMaxCacheTTL(cfg.Ipns.MaxCacheTTL.WithDefault(config.DefaultIpnsMaxCacheTTL)),
		}

		subAPI.routing = offlineroute.NewOfflineRouter(irouting.DHTValueDatastore(subAPI.repo.Datastore()), subAPI.recordValidator)

		subAPI.namesys, err = namesys.NewNameSystem(subAPI.routing, nsOptions...)
		if err != nil {
			return nil, fmt.Errorf("error constructing namesys: %w", err)
		}

		subAPI.peerstore = nil
		subAPI.peerHost = nil
		subAPI.recordValidator = nil
	}

	if settings.Offline || !settings.FetchBlocks {
		subAPI.exchange = offlinexch.Exchange(subAPI.blockstore)
		subAPI.blocks = bserv.New(subAPI.blockstore, subAPI.exchange,
			bserv.WriteThrough(cfg.Datastore.WriteThrough.WithDefault(config.DefaultWriteThrough)),
		)
		subAPI.dag = dag.NewDAGService(subAPI.blocks)
	}

	return subAPI, nil
}

View on GitHub (pinned to 329838acdf)