ipfs/kubo · error

unknown autonat mode: %s

Error message

unknown autonat mode: %s

What it means

AutoNATServiceMode.UnmarshalText parses the AutoNAT.Mode config string into the typed enum. It accepts 'enabled', 'disabled', and 'legacy-v1'; any other string hits the default branch and returns 'unknown autonat mode: %s'. This is a strict config-schema validation error at config load time.

Source

Thrown at config/autonat.go:39

	// AutoNATService.
	AutoNATServiceDisabled
	// AutoNATServiceEnabledV1Only forces use of V1 and disables V2
	// (used for testing)
	AutoNATServiceEnabledV1Only
)

func (m *AutoNATServiceMode) UnmarshalText(text []byte) error {
	switch string(text) {
	case "":
		*m = AutoNATServiceUnset
	case "enabled":
		*m = AutoNATServiceEnabled
	case "disabled":
		*m = AutoNATServiceDisabled
	case "legacy-v1":
		*m = AutoNATServiceEnabledV1Only
	default:
		return fmt.Errorf("unknown autonat mode: %s", string(text))
	}
	return nil
}

func (m AutoNATServiceMode) MarshalText() ([]byte, error) {
	switch m {
	case AutoNATServiceUnset:
		return nil, nil
	case AutoNATServiceEnabled:
		return []byte("enabled"), nil
	case AutoNATServiceDisabled:
		return []byte("disabled"), nil
	case AutoNATServiceEnabledV1Only:
		return []byte("legacy-v1"), nil
	default:
		return nil, fmt.Errorf("unknown autonat mode: %d", m)
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Set AutoNAT.Mode to one of: enabled, disabled, legacy-v1 (ipfs config AutoNAT.Mode enabled)
2. Check the exact spelling/case against the current version's docs/config.md
3. If migrating from an old mode name, map it: 'enabled' for default service, 'legacy-v1' for v1-only behavior, 'disabled' to turn it off

Example fix

// before (config.json)
"AutoNAT": { "Mode": "on" }
// after
"AutoNAT": { "Mode": "enabled" }

var mode config.AutoNATServiceMode
if err := mode.UnmarshalText([]byte(cfgValue)); err != nil {
    return fmt.Errorf("bad AutoNAT.Mode %q: valid values are enabled, disabled, legacy-v1", cfgValue)
}

func validAutoNATMode(s string) bool {
    switch s { case "enabled", "disabled", "legacy-v1": return true }
    return false
}

if err := json.Unmarshal(rawCfg, &cfg); err != nil {
    var ue *json.UnmarshalTypeError
    if errors.As(err, &ue) && strings.Contains(ue.Error(), "autonat") { fixAutoNATMode() }
    return err
}

When it happens

Trigger: Setting AutoNAT.Mode in the kubo config (or via ipfs config AutoNAT.Mode X) to a value outside {enabled, disabled, legacy-v1}, e.g. 'enable', 'auto', 'true', or an older removed mode name.

Common situations: Config copied from documentation of a different version where a mode name changed; typo when hand-editing config.json; migration scripts writing boolean-like values ('on'/'off') instead of enum strings.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• private networking (swarm.key / LIBP2P_FORCE_PNET) does not
• Routing.AcceleratedDHTClient option is set even tho Routing.
• serveHTTPApi: GetConfig() failed: %s
• serveHTTPApi: invalid API address: %q (err: %s)
• private network does not work with Routing.Type=auto. Update

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