invalid configuration: Provide.DHT.MaxWorkers cannot be 0 wh

Error message

invalid configuration: Provide.DHT.MaxWorkers cannot be 0 when Provide.DHT.SweepEnabled=true. Set Provide.DHT.MaxWorkers to a positive value (e.g., 16) to control resource usage. Documentation: https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtmaxworkers

What it means

When the DHT provider sweep system is enabled, at least one worker is required to make progress. validateDaemonConfig rejects Provide.DHT.SweepEnabled=true together with Provide.DHT.MaxWorkers=0, which would silently provide nothing while consuming the sweep schedule.

Source

Thrown at cmd/ipfs/kubo/daemon.go:984

	// This should never happen for regular users, but is useful error for people who have Docker orchestration
	// that blindly sets config keys (overriding automatic Kubo migration).
	//nolint:staticcheck // intentionally checking deprecated fields
	if cfg.Provider.Enabled != config.Default || !cfg.Provider.Strategy.IsDefault() || !cfg.Provider.WorkerCount.IsDefault() {
		return errors.New("deprecated configuration detected. Manually migrate 'Provider' fields to 'Provide' and remove 'Provider' from your config. Documentation: https://github.com/ipfs/kubo/blob/master/docs/config.md#provide")
	}
	//nolint:staticcheck // intentionally checking deprecated fields
	if !cfg.Reprovider.Interval.IsDefault() || !cfg.Reprovider.Strategy.IsDefault() {
		return errors.New("deprecated configuration detected. Manually migrate 'Reprovider' fields to 'Provide': Reprovider.Strategy -> Provide.Strategy, Reprovider.Interval -> Provide.DHT.Interval. Remove 'Reprovider' from your config. Documentation: https://github.com/ipfs/kubo/blob/master/docs/config.md#provide")
	}
	if cfg.Provide.Strategy.WithDefault("") == "flat" {
		return errors.New("Provide.Strategy='flat' is no longer supported. Use 'all' instead. Documentation: https://github.com/ipfs/kubo/blob/master/docs/config.md#providestrategy")
	}
	if cfg.Experimental.StrategicProviding {
		return errors.New("Experimental.StrategicProviding was removed. Remove it from your config. Documentation: https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#strategic-providing")
	}
	if cfg.Provide.DHT.SweepEnabled.WithDefault(config.DefaultProvideDHTSweepEnabled) &&
		cfg.Provide.DHT.MaxWorkers.WithDefault(config.DefaultProvideDHTMaxWorkers) == 0 {
		return errors.New("invalid configuration: Provide.DHT.MaxWorkers cannot be 0 when Provide.DHT.SweepEnabled=true. Set Provide.DHT.MaxWorkers to a positive value (e.g., 16) to control resource usage. Documentation: https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtmaxworkers")
	}
	if routingOption == routingOptionDelegatedKwd && cfg.Provide.Enabled.WithDefault(config.DefaultProvideEnabled) {
		return errors.New("Routing.Type=delegated does not support content providing. Set Provide.Enabled=false in your config")
	}

	return nil
}

func validateDaemonEnvironment() error {
	if flag := os.Getenv("IPFS_REUSEPORT"); flag != "" {
		return errors.New("support for IPFS_REUSEPORT was removed. Use LIBP2P_TCP_REUSEPORT instead")
	}
	return nil
}

// printLibp2pPorts prints which ports are opened to facilitate swarm connectivity.
func printLibp2pPorts(node *core.IpfsNode) {
	if !node.IsOnline {

View on GitHub (pinned to 329838acdf)

Solutions

Set a positive worker count: `ipfs config --json Provide.DHT.MaxWorkers 16`
If no providing is wanted, disable the sweep instead: `ipfs config --json Provide.DHT.SweepEnabled false` (or set Provide.Enabled=false)
Check defaults in docs/config.md#providedhtmaxworkers

Example fix

// before (config.json)
"Provide": { "DHT": { "SweepEnabled": true, "MaxWorkers": 0 } }

// after
"Provide": { "DHT": { "SweepEnabled": true, "MaxWorkers": 16 } }

Defensive patterns

Strategy: validation

Validate before calling

// enforce workers>=1 when sweep enabled (mirrors daemon logic)
sweep=$(jq -r '.Provide.DHT.SweepEnabled // "<default>"' "$IPFS_PATH/config")
w=$(jq -r '.Provide.DHT.MaxWorkers // "<default>"' "$IPFS_PATH/config")
if [ "$sweep" = true ] && { [ "$w" = 0 ] || { [ "$w" = "<default>" ] && [ "$(jq -r '.Provide.DHT.MaxWorkers // 0' "$IPFS_PATH/config")" = 0 ]; }; }; then echo "Set Provide.DHT.MaxWorkers>0 or disable SweepEnabled"; fi

Try / catch

if err := daemonFunc(...); err != nil {
    if strings.Contains(err.Error(), "MaxWorkers cannot be 0") {
        log.Fatalf("fix Provide.DHT config: %v", err)
    }
}

Prevention

Never set MaxWorkers=0 while SweepEnabled=true
To throttle providing, lower workers to a small positive value instead of 0
To stop providing, set Provide.Enabled=false instead
Validate JSON config numerics with jq before deploy

When it happens

Trigger: `ipfs daemon` when Provide.DHT.SweepEnabled resolves to true (explicitly or via default) and Provide.DHT.MaxWorkers is explicitly 0 or resolves to the default that the operator overrode to 0.

Common situations: Operators zeroing MaxWorkers to 'disable' providing while leaving SweepEnabled on; config templates setting MaxWorkers=0 for resource limits without disabling the sweep.

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/6a206dc68b337b3c. Report an issue: GitHub.