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

Set `ipfs config --json Ipns.ResolveCacheSize 128` (or another positive value; 0 selects the built-in DefaultIpnsCacheSize)

ipfs/kubo · error

cannot specify negative resolve cache size

Error message

cannot specify negative resolve cache size

What it means

`Ipns.ResolveCacheSize` controls how many IPNS records the local resolver caches. Negative values are nonsensical and rejected during Online (node) construction with this plain error, before any IPNS subsystem starts.

Source

Thrown at core/node/groups.go:321

		fx.Invoke(libp2p.PstoreAddSelfKeys),
	)
}

// IPNS groups namesys related units
var IPNS = fx.Options(
	fx.Provide(RecordValidator),
)

// Online groups online-only units
func Online(bcfg *BuildCfg, cfg *config.Config, userResourceOverrides rcmgr.PartialLimitConfig) fx.Option {
	// Namesys params

	ipnsCacheSize := cfg.Ipns.ResolveCacheSize
	if ipnsCacheSize == 0 {
		ipnsCacheSize = DefaultIpnsCacheSize
	}
	if ipnsCacheSize < 0 {
		return fx.Error(errors.New("cannot specify negative resolve cache size"))
	}

	// Republisher params

	var repubPeriod, recordLifetime time.Duration

	if cfg.Ipns.RepublishPeriod != "" {
		d, err := time.ParseDuration(cfg.Ipns.RepublishPeriod)
		if err != nil {
			return fx.Error(fmt.Errorf("failure to parse config setting IPNS.RepublishPeriod: %s", err))
		}

		if !util.Debug && (d < time.Minute || d > (time.Hour*24)) {
			return fx.Error(fmt.Errorf("config setting IPNS.RepublishPeriod is not between 1min and 1day: %s", d))
		}

		repubPeriod = d
	}

View on GitHub (pinned to 329838acdf)

Solutions

Set `ipfs config --json Ipns.ResolveCacheSize 128` (or another positive value; 0 selects the built-in DefaultIpnsCacheSize)
Remove the key entirely to fall back to the default
Re-check any script that writes ResolveCacheSize to avoid emitting negative values

Example fix

// before (config.json)
"Ipns": { "ResolveCacheSize": -10 }
// after
"Ipns": { "ResolveCacheSize": 128 }

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Ipns.ResolveCacheSize < 0 {
	return errors.New("Ipns.ResolveCacheSize must be >= 0 (0 = default)")
}

Prevention

Use 0 (or omit the key) to request the default cache size
Sanitize numeric config values written by scripts
Document that ResolveCacheSize is a non-negative integer

When it happens

Trigger: `cfg.Ipns.ResolveCacheSize < 0` in the config when the Online fx group builds (called from Networked).

Common situations: Hand-edited config with a negative number; scripted config writes that subtract or misparse an integer; copying a placeholder value like -1 meaning 'default' from third-party docs.

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/9559789be4060737. Report an issue: GitHub.