cilium/cilium · error

invalid xDS mode %q

Error message

invalid xDS mode %q

What it means

XDSMode.Validate() returns this when the configured xDS mode string does not match any known mode constant. It is the 'invalid value' branch, as opposed to the 'known but unimplemented' branch. The configuration contains a typo or an entirely unknown mode name.

Source

Thrown at pkg/envoy/config/config.go:57

)

func (v XDSMode) IsADS() bool {
	return strings.HasSuffix(string(v), "ads")
}

func (v XDSMode) IsStrictADS() bool {
	return strings.HasPrefix(string(v), "strict-")
}

// Validate validates and normalizes the XDSMode
func (v XDSMode) Validate() error {
	switch v {
	case EnvoyXDSModeSplit, EnvoyXDSModeDeltaSplit, EnvoyXDSModeADS, EnvoyXDSModeStrictADS:
		return nil
	case EnvoyXDSModeDeltaADS, EnvoyXDSModeStrictDeltaADS:
		return fmt.Errorf("unimplemented xDS mode %q", v)
	default:
		return fmt.Errorf("invalid xDS mode %q", v)
	}
}

func (v XDSMode) EnvoyApiType() envoy_config_core.ApiConfigSource_ApiType {
	switch v {
	case EnvoyXDSModeDeltaSplit:
		return envoy_config_core.ApiConfigSource_DELTA_GRPC
	case EnvoyXDSModeADS, EnvoyXDSModeStrictADS:
		return envoy_config_core.ApiConfigSource_AGGREGATED_GRPC
	case EnvoyXDSModeDeltaADS, EnvoyXDSModeStrictDeltaADS:
		return envoy_config_core.ApiConfigSource_AGGREGATED_DELTA_GRPC
	}
	return envoy_config_core.ApiConfigSource_GRPC
}

// implement the pflag.Value interface
var _xdsMode_ XDSMode
var _ pflag.Value = &_xdsMode_

View on GitHub (pinned to ac7b90affa)

Solutions

1. Correct the mode to one of: split, delta-split, ads, strict-ads (delta ADS variants exist but are unimplemented)
2. Echo the configured value and compare exactly against the allowed constants (matching is case-sensitive)
3. Validate the rendered Helm/ConfigMap output to ensure the value isn't empty or mangled

Example fix

// before
--xds-mode="Delta Split"
// after
--xds-mode="delta-split"

func knownXDSMode(s string) bool {
    switch config.XDSMode(s) {
    case config.EnvoyXDSModeSplit, config.EnvoyXDSModeDeltaSplit,
        config.EnvoyXDSModeADS, config.EnvoyXDSModeStrictADS,
        config.EnvoyXDSModeDeltaADS, config.EnvoyXDSModeStrictDeltaADS:
        return true
    }
    return false
}

if err := mode.Validate(); err != nil {
    if strings.Contains(err.Error(), "invalid xDS mode") {
        return fmt.Errorf("config typo in xds-mode %q; allowed: split, delta-split, ads, strict-ads", mode)
    }
    return err
}

When it happens

Trigger: Passing an unrecognized value for the xDS mode config option (e.g. --xds-mode=splt, empty/whitespace value, or a mode name from a different product).

Common situations: Typos in Helm values or ConfigMaps, case-sensitivity mistakes, config templating that yields an empty or wrong string, docs from a different Cilium version.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• nodeId is empty
• invalid version info
• invalid node format
• unspecified Listener name
• duplicate Listener name %q

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/856f35706e0f6899. Report an issue: GitHub.