ipfs/kubo · error

cannot specify negative resolve cache size

Error message

cannot specify negative resolve cache size

What it means

When the node is constructed with `Ipns.Offline` mode, coreapi reads the configured IPNS resolve cache size (`Ipns.ResolveCacheSize`). A zero value means "use the default", but any negative value is nonsensical for a cache capacity, so WithOptions rejects the configuration up front instead of failing later inside namesys.

Source

Thrown at core/coreapi/coreapi.go:225

		}
		if n.Mounts.Ipns != nil && n.Mounts.Ipns.IsActive() {
			return errors.New("cannot manually publish while IPNS is mounted")
		}
		return nil
	}

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

	if settings.Offline {
		cs := cfg.Ipns.ResolveCacheSize
		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

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Ipns.ResolveCacheSize to 0 in the config to get the default (node.DefaultIpnsCacheSize).
2. Set Ipns.ResolveCacheSize to a positive integer sized for your workload.
3. Remove the Ipns.ResolveCacheSize key entirely so the default applies.

Example fix

// before (config)
"Ipns": { "Offline": true, "ResolveCacheSize": -1 }
// after
"Ipns": { "Offline": true, "ResolveCacheSize": 0 }

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

func validResolveCacheSize(cs int) bool { return cs >= 0 }

n, err := coreapi.NewNode(node, opts)
if errors.Is(err, errNegativeCache) || strings.Contains(err.Error(), "negative resolve cache size") {
    // fix config or fall back to defaults
}

When it happens

Trigger: Calling coreapi.NewNode(node, &coreapi.APIOptions{Offline: true}) when the repo config contains a negative Ipns.ResolveCacheSize, e.g. loaded from a hand-edited or programmatically generated config file.

Common situations: Users hand-editing the config JSON and setting Ipns.ResolveCacheSize to -1 to try to 'disable' the IPNS cache; provisioning scripts that compute the cache size (e.g. from memory) and overflow or miscalculate into a negative number.

Related errors

• can't put while offline: pass `--allow-offline` to store loc
• failed to read config: %w
• no delegated publishers configured: add Ipns.DelegatedPublis
• error constructing namesys: %w
• failed to read config: %w

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