ipfs/kubo · error

Provide.Strategy='flat' is no longer supported. Use 'all' in

Error message

Provide.Strategy='flat' is no longer supported. Use 'all' instead. Documentation: https://github.com/ipfs/kubo/blob/master/docs/config.md#providestrategy

What it means

The 'flat' provide strategy was removed from Kubo; validateDaemonConfig rejects Provide.Strategy='flat' at daemon startup and directs users to 'all'. Flat providing (legacy flatfs-era behavior) is no longer implemented, so the config value is invalid.

Source

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

func validateDaemonConfig(cfg *config.Config, routingOption string, privateNetwork bool) error {
	if privateNetwork && (routingOption == routingOptionAutoKwd || routingOption == routingOptionAutoClientKwd) {
		return errors.New("private network does not work with Routing.Type=auto. Update your config to Routing.Type=dht (or none, and do manual peering)")
	}

	// Check for deprecated Provider/Reprovider configuration after migration.
	// 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")

View on GitHub (pinned to 329838acdf)

Solutions

  1. Set the new value: `ipfs config Provide.Strategy all`
  2. Or choose another supported value (e.g. 'pins', 'mfs', 'roots', 'pinned', 'edge') per docs/config.md#providestrategy
  3. Update deployment templates that still emit 'flat'

Example fix

// before (config.json)
"Provide": { "Strategy": "flat" }

// after
$ ipfs config Provide.Strategy all
Defensive patterns

Strategy: validation

Validate before calling

// reject removed strategy before start
s=$(jq -r '.Provide.Strategy // empty' "$IPFS_PATH/config")
[ "$s" = flat ] && echo "Provide.Strategy=flat removed; use all (docs/config.md#providestrategy)"

Try / catch

if err := daemonFunc(...); err != nil {
    if strings.Contains(err.Error(), "no longer supported. Use 'all'") {
        log.Fatalf("replace Provide.Strategy: %v", err)
    }
}

Prevention

When it happens

Trigger: `ipfs daemon` with Provide.Strategy explicitly or effectively set to "flat" in the config (after migrating legacy Provider.Strategy=flat or Reprovider.Strategy=flat).

Common situations: Configs migrated from old flat-namespace nodes whose strategy value was copied verbatim; scripts templating strategy='flat' from old documentation.

Related errors

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