ipfs/kubo · error

error constructing namesys: %w

Error message

error constructing namesys: %w

What it means

newGatewayBackend builds the IPNS name system (namesys) via namesys.NewNameSystem, wiring in the datastore, DNS resolver, cache size, and MaxCacheTTL. If namesys construction fails for any reason, the error is wrapped with 'error constructing namesys' and gateway startup aborts.

Source

Thrown at core/corehttp/gateway.go:181

		cs := cfg.Ipns.ResolveCacheSize
		if cs == 0 {
			cs = node.DefaultIpnsCacheSize
		}
		if cs < 0 {
			return nil, fmt.Errorf("cannot specify negative resolve cache size")
		}

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

		vsRouting = offlineroute.NewOfflineRouter(irouting.DHTValueDatastore(n.Repo.Datastore()), n.RecordValidator)
		nsys, err = namesys.NewNameSystem(vsRouting, nsOptions...)
		if err != nil {
			return nil, fmt.Errorf("error constructing namesys: %w", err)
		}

		// Gateway.NoFetch=true requires offline path resolver
		// to avoid fetching missing blocks during path traversal
		pathResolver = n.OfflineUnixFSPathResolver
	}

	backend, err := gateway.NewBlocksBackend(bserv,
		gateway.WithValueStore(vsRouting),
		gateway.WithNameSystem(nsys),
		gateway.WithResolver(pathResolver),
	)
	if err != nil {
		return nil, err
	}
	return &offlineGatewayErrWrapper{gwimpl: backend}, nil
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Inspect the wrapped (%w) cause in the full error message — it names the underlying failure (datastore, resolver, or option error).
2. Verify IPNS settings: `ipfs config --json Ipns` — ResolveCacheSize must be >= 0 and MaxCacheTTL a valid duration.
3. Ensure the repo datastore is accessible and not locked by another daemon process (`pkill -f 'ipfs daemon'`, then retry).
4. Check `DNSResolver` config entries are valid resolvers; reset with `ipfs config --json DNSResolver '{}'` if unsure.
5. Run `ipfs repo fsck` / verify repo health if the cause points at the datastore.

Example fix

// before (invalid option reaching namesys)
ipfs config --json Ipns.ResolveCacheSize -5
// error constructing namesys: ...

// after
ipfs config --json Ipns.ResolveCacheSize 0 // default
ipfs daemon

// before gateway startup, sanity-check the inputs namesys consumes
if cfg.Ipns.ResolveCacheSize < 0 { return errors.New("negative ResolveCacheSize") }
if _, err := time.ParseDuration(string(cfg.Ipns.MaxCacheTTL.WithDefault(config.DefaultIpnsMaxCacheTTL))); err != nil {
    return fmt.Errorf("invalid Ipns.MaxCacheTTL: %w", err)
}
// ensure the repo datastore opens
if _, err := n.Repo.Datastore().Query(context.Background(), query.Query{}); err != nil {
    return fmt.Errorf("datastore unavailable: %w", err)
}

_, err := corehttp.ListenAndServe(...) // or gateway option application
var initErr error
if err != nil && strings.Contains(err.Error(), "error constructing namesys") {
    // unwrap: log the %w cause, verify repo lock/datastore and Ipns config, then retry
    log.Errorw("namesys init failed", "err", err)
    initErr = err
}
return initErr

When it happens

Trigger: Calling the gateway ServeOption (newGatewayBackend) when namesys.NewNameSystem returns an error — typically due to an invalid combination of Ipns options (e.g. bad ResolveCacheSize reaching namesys.WithCache), an unavailable Repo datastore, or a malformed DNSResolver configuration.

Common situations: Corrupted or locked datastore (repo in use by another daemon); invalid `Ipns.ResolveCacheSize`/`Ipns.MaxCacheTTL` config values; custom `DNSResolver` addresses in config that fail validation; running a gateway option chain against a partially initialized node in embedded usage.

Related errors

• error constructing namesys: %w
• cannot specify negative resolve cache size
• %s : %w
• could not resolve name
• Name.Resolve: depth other than 1 or %d not supported

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