What causes "cannot specify negative resolve cache size" in ipfs/kubo?

Set the value to a non-negative integer: `ipfs config --json Ipns.ResolveCacheSize 128` (entries), or 0 to use kubo's default (node.DefaultIpnsCacheSize).

ipfs/kubo · error

cannot specify negative resolve cache size

Error message

cannot specify negative resolve cache size

What it means

When building the gateway backend, kubo reads the `Ipns.ResolveCacheSize` config value to size the IPNS resolution cache; 0 means 'use the default'. A negative value is meaningless for a cache size, so newGatewayBackend rejects it with this error before the gateway can start.

Source

Thrown at core/corehttp/gateway.go:168

	cfg, err := n.Repo.Config()
	if err != nil {
		return nil, err
	}

	bserv := n.Blocks
	var vsRouting routing.ValueStore = n.Routing
	nsys := n.Namesys
	pathResolver := n.UnixFSPathResolver

	if cfg.Gateway.NoFetch {
		bserv = blockservice.New(bserv.Blockstore(), offline.Exchange(bserv.Blockstore()))

		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

View on GitHub (pinned to 329838acdf)

Solutions

Set the value to a non-negative integer: `ipfs config --json Ipns.ResolveCacheSize 128` (entries), or 0 to use kubo's default (node.DefaultIpnsCacheSize).
Validate the config before starting: `ipfs config --json Ipns.ResolveCacheSize` and confirm it is >= 0.
If the goal is to disable caching, use the supported knob `Ipns.MaxCacheTTL` (e.g. a tiny TTL) instead of a negative cache size.
Restore a known-good config: `ipfs config --json Ipns.ResolveCacheSize 0`.

Example fix

// before (invalid config)
ipfs config --json Ipns.ResolveCacheSize -1

// after
ipfs config --json Ipns.ResolveCacheSize 0   // 0 = default cache size

Defensive patterns

Strategy: validation

Validate before calling

cs, err := repo.Config().Ipns.ResolveCacheSize // int
if err != nil {
    return err
}
if cs < 0 {
    return fmt.Errorf("Ipns.ResolveCacheSize must be >= 0, got %d", cs)
}

Prevention

Treat config edits as code: keep Ipns.ResolveCacheSize in version control or infrastructure-as-code with a >= 0 check.
Use 0 (default) instead of hand-picking sizes unless you measured a need.
Run `ipfs config --json Ipns.ResolveCacheSize` in deploy scripts before starting the daemon.
Remember negative values are never valid for cache sizes; to reduce caching use Ipns.MaxCacheTTL instead.

When it happens

Trigger: Setting `ipfs config --json Ipns.ResolveCacheSize -1` (or any negative number) and then starting the daemon, which fails during gateway construction.

Common situations: Hand-edited config files with a typo'd minus sign; copy-pasted tuning snippets intended for a different option; operators trying to 'disable' the cache by using a negative size instead of a valid value.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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