What causes "error constructing namesys: %w" in ipfs/kubo?

Inspect the wrapped %w cause to identify the actual namesys failure (datastore, resolver, or cache option).

error constructing namesys: %w

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.

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)

Solutions

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

Defensive patterns

Strategy: try-catch

Validate before calling

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")
}
}

Try / catch

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
}

Prevention

Open and sanity-check the datastore before building an offline API node
Pass only well-tested namesys options; add custom resolvers gradually
Log the wrapped cause (%w) to distinguish resolver vs datastore failures

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

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