Provide.DHT.MaxProvideConnsPerWorker must be positive, got %

Error message

Provide.DHT.MaxProvideConnsPerWorker must be positive, got %d

What it means

Provide.DHT.MaxProvideConnsPerWorker caps concurrent connections per worker when sending provider records in sweep mode; a value of zero or less would stall all provider-record sends. ValidateProvideConfig requires an explicitly set value to be strictly positive.

Source

Thrown at config/provide.go:263

		workers := cfg.DHT.DedicatedPeriodicWorkers.WithDefault(DefaultProvideDHTDedicatedPeriodicWorkers)
		if workers < 0 {
			return fmt.Errorf("Provide.DHT.DedicatedPeriodicWorkers must be non-negative, got %d", workers)
		}
	}

	// Validate DedicatedBurstWorkers
	if !cfg.DHT.DedicatedBurstWorkers.IsDefault() {
		workers := cfg.DHT.DedicatedBurstWorkers.WithDefault(DefaultProvideDHTDedicatedBurstWorkers)
		if workers < 0 {
			return fmt.Errorf("Provide.DHT.DedicatedBurstWorkers must be non-negative, got %d", workers)
		}
	}

	// Validate MaxProvideConnsPerWorker
	if !cfg.DHT.MaxProvideConnsPerWorker.IsDefault() {
		conns := cfg.DHT.MaxProvideConnsPerWorker.WithDefault(DefaultProvideDHTMaxProvideConnsPerWorker)
		if conns <= 0 {
			return fmt.Errorf("Provide.DHT.MaxProvideConnsPerWorker must be positive, got %d", conns)
		}
	}

	// Validate KeystoreBatchSize
	if !cfg.DHT.KeystoreBatchSize.IsDefault() {
		batchSize := cfg.DHT.KeystoreBatchSize.WithDefault(DefaultProvideDHTKeystoreBatchSize)
		if batchSize <= 0 {
			return fmt.Errorf("Provide.DHT.KeystoreBatchSize must be positive, got %d", batchSize)
		}
	}

	// Validate OfflineDelay
	if !cfg.DHT.OfflineDelay.IsDefault() {
		delay := cfg.DHT.OfflineDelay.WithDefault(DefaultProvideDHTOfflineDelay)
		if delay < 0 {
			return fmt.Errorf("Provide.DHT.OfflineDelay must be non-negative, got %v", delay)
		}
	}

View on GitHub (pinned to 329838acdf)

Solutions

Set Provide.DHT.MaxProvideConnsPerWorker to a positive integer (default 20)
Remove the key to use the default
To stop providing, set Provide.Enabled=false rather than zeroing worker/conns knobs

Example fix

// before
"MaxProvideConnsPerWorker": 0
// after
"MaxProvideConnsPerWorker": 20

Defensive patterns

Strategy: validation

Validate before calling

if c := cfg.Provide.DHT.MaxProvideConnsPerWorker; !c.IsDefault() && c.WithDefault(config.DefaultProvideDHTMaxProvideConnsPerWorker) <= 0 {
	return errors.New("MaxProvideConnsPerWorker must be positive")
}

Try / catch

if err := config.ValidateProvideConfig(cfg.Provide); err != nil {
	if strings.Contains(err.Error(), "MaxProvideConnsPerWorker must be positive") {
		cfg.Provide.DHT.MaxProvideConnsPerWorker = nil // default 20
	}
	return err
}

Prevention

Never zero this knob to pause provides; use Provide.Enabled=false
Clamp generated values to >= 1
Keep the default 20 unless benchmarking showed a need to change it

When it happens

Trigger: Node startup when Provide.DHT.MaxProvideConnsPerWorker is explicitly set (non-default) to 0 or a negative integer in the config.

Common situations: Operator setting the value to 0 intending to pause provides (use Provide.Enabled=false instead); template config left with a placeholder 0; sign errors in scripts.

Related errors

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