private network does not work with Routing.Type=auto. Update

Error message

private network does not work with Routing.Type=auto. Update your config to Routing.Type=dht (or none, and do manual peering)

What it means

validateDaemonConfig rejects daemon startup when Swarm.Key (private network) is combined with Routing.Type=auto or autoclient. Auto routing may use public DHT/client routers that bypass the private swarm, which is incompatible with private networks. The operator must pick an explicit routing mode.

Source

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

	return errc, nil
}

func rewriteMaddrToUseLocalhostIfItsAny(maddr ma.Multiaddr) ma.Multiaddr {
	first, rest := ma.SplitFirst(maddr)

	switch {
	case first.Equal(&manet.IP4Unspecified[0]):
		return manet.IP4Loopback.Encapsulate(rest)
	case first.Equal(&manet.IP6Unspecified[0]):
		return manet.IP6Loopback.Encapsulate(rest)
	default:
		return maddr // not ip
	}
}

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")

View on GitHub (pinned to 329838acdf)

Solutions

Set explicit routing: `ipfs config Routing.Type dht` (full DHT inside the private network)
Or disable routing entirely: `ipfs config Routing.Type none` and use manual peering (`Peering.Peers`)
If CLI flag used, change `--routing=auto` to `--routing=dht` or `--routing=none`
Remove the swarm key if a private network was not intended

Example fix

// before
$ ipfs config Routing.Type
auto   # with Swarm.Key set
Error: private network does not work with Routing.Type=auto...

// after
$ ipfs config Routing.Type dht
$ ipfs daemon

Defensive patterns

Strategy: validation

Validate before calling

// reject invalid combo before launching daemon
cfg=$(ipfs config Routing.Type); has_key=$(test -f "$IPFS_PATH/swarm.key" && echo yes)
if [ "$has_key" = yes ] && { [ "$cfg" = auto ] || [ "$cfg" = autoclient ]; }; then echo "private network requires Routing.Type=dht or none"; fi

Try / catch

if err := daemonFunc(...); err != nil {
    if strings.Contains(err.Error(), "private network does not work") {
        log.Fatalf("fix routing config: %v", err)
    }
}

Prevention

Never combine swarm keys with Routing.Type=auto in provisioning templates
Pin explicit Routing.Type (dht|none) for private-network deployments
Audit Docker/K8s env writers that set Routing.* blindly
Test config with `ipfs config show` before rolling out to the fleet

When it happens

Trigger: Running `ipfs daemon` in a private network (Swarm.Key set / LIBP2P_SWARM_KEY or --swarm-key) while config has Routing.Type=auto or Routing.Type=autoclient, or the CLI passes --routing=auto with a swarm key.

Common situations: Private/clusters deployments provisioned by Docker/K8s orchestration that blindly sets Routing.Type=auto; nodes migrated to auto routing after joining a permissioned network.

Related errors

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