ipfs/kubo · error

unknown autonat mode: %d

Error message

unknown autonat mode: %d

What it means

AutoNATServiceMode.MarshalText hit its default arm: the in-memory enum value does not correspond to any known mode (unset, enabled, disabled, legacy-v1), so it has no textual representation for the config file. Almost always the result of a corrupted or programmatic value, not user input.

Source

Thrown at config/autonat.go:55

		*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)
	}
}

// AutoNATConfig configures the node's AutoNAT subsystem.
type AutoNATConfig struct {
	// ServiceMode configures the node's AutoNAT service mode.
	ServiceMode AutoNATServiceMode `json:",omitempty"`

	// Throttle configures AutoNAT dialback throttling.
	//
	// If unset, the conservative libp2p defaults will be unset. To help the
	// network, please consider setting this and increasing the limits.
	//
	// By default, the limits will be a total of 30 dialbacks, with a
	// per-peer max of 3 peer, resetting every minute.
	Throttle *AutoNATThrottleConfig `json:",omitempty"`
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Set Swarm.AutoNATServiceMode in the config to one of the documented strings (enabled, disabled, legacy-v1)
2. Remove the key to let it take its default
3. Check for code that constructs AutoNATConfig with a raw numeric mode

When it happens

Trigger: Thrown at config/autonat.go:55 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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