ipfs/kubo · error

unrecognized routing option: %s

Error message

unrecognized routing option: %s

What it means

Raised in P2PRouter when the user-supplied Routing.Type value in the config does not match any known keyword (dht, dhtclient, none, delegated, custom). The switch over the routing option falls through to default, meaning the string was never validated before node construction, so the offending value is passed straight into the error.

Source

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

		ncfg.Routing = libp2p.DHTServerOption
	case routingOptionNoneKwd:
		ncfg.Routing = libp2p.NilRouterOption
	case routingOptionDelegatedKwd:
		ncfg.Routing = libp2p.ConstructDelegatedOnlyRouting(cfg)
	case routingOptionCustomKwd:
		if cfg.Routing.AcceleratedDHTClient.WithDefault(config.DefaultAcceleratedDHTClient) {
			return errors.New("Routing.AcceleratedDHTClient option is set even tho Routing.Type is custom, using custom .AcceleratedDHTClient needs to be set on DHT routers individually")
		}
		ncfg.Routing = libp2p.ConstructDelegatedRouting(
			cfg.Routing.Routers,
			cfg.Routing.Methods,
			cfg.Identity.PeerID,
			cfg.Addresses,
			cfg.Identity.PrivKey,
			cfg.HTTPRetrieval.Enabled.WithDefault(config.DefaultHTTPRetrievalEnabled),
		)
	default:
		return fmt.Errorf("unrecognized routing option: %s", routingOption)
	}

	// Resolve agent version suffix:
	// Version.AgentSuffix > --agent-version-suffix > implicit (build origin).
	versionSuffixFromCli, _ := req.Options[agentVersionSuffix].(string)
	versionSuffix := cfg.Version.AgentSuffix.WithDefault(versionSuffixFromCli)
	if versionSuffix == "" {
		versionSuffix = version.ImplicitAgentSuffix()
	}
	if versionSuffix != "" {
		version.SetUserAgentSuffix(versionSuffix)
	}

	if err := validateDaemonConfig(cfg, routingOption, isPrivateNetwork); err != nil {
		return err
	}

	if err := validateDaemonEnvironment(); err != nil {

View on GitHub (pinned to 329838acdf)

Solutions

1. Check `ipfs daemon --help` for the exact accepted --routing keywords
2. Use a valid value such as default, dhtclient, dhtserver, none, delegated, or custom
3. Fix casing: keywords are matched exactly, e.g. autoClient, dhtclient

Example fix

// before
ipfs daemon --routing=DHTClient
// after
ipfs daemon --routing=dhtclient

valid := []string{"default","auto","autoClient","dhtclient","dhtserver","none","delegated","custom"}
if !slices.Contains(valid, routingFlag) {
    return fmt.Errorf("unrecognized routing option: %s", routingFlag)
}

When it happens

Trigger: Running `ipfs daemon --routing=<value>` where <value> is not one of: default, auto, autoClient, dhtclient, dhtserver, none, delegated, custom, supernode (supernode fails separately).

Common situations: Typos (e.g. --routing=DHTClient with wrong casing), values copied from other IPFS implementations, or stale scripts from removed options.

Related errors

• supernode routing was never fully implemented and has been r
• Routing.AcceleratedDHTClient option is set even tho Routing.
• invalid type '%s', must be one of {direct, indirect, recursi
• private networking (swarm.key / LIBP2P_FORCE_PNET) does not
• closing plugins: %w

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