The value --%s=%s is not supported as default under annotati

Error message

The value --%s=%s is not supported as default under annotation mode

What it means

When annotation-based load-balancing mode selection is enabled (LBModeAnnotation), the default --lb-mode may not be 'hybrid', because hybrid cannot be expressed per-service via annotations. NewConfig refuses the configuration in that combination.

Source

Thrown at pkg/loadbalancer/config.go:497

		if extMax >= cfg.NodePortMin {
			return Config{}, fmt.Errorf("extended NodePort NAT range must not overlap with NodePort range")
		}
		cfg.NodePortMinNATExt = extMin
		cfg.NodePortMaxNATExt = extMax
	}

	if cfg.LBAlgorithm != LBAlgorithmRandom &&
		cfg.LBAlgorithm != LBAlgorithmMaglev {
		return Config{}, fmt.Errorf("Invalid value for --%s: %s", LBAlgorithmName, cfg.LBAlgorithm)
	}

	if cfg.LBMode != LBModeSNAT && cfg.LBMode != LBModeDSR && cfg.LBMode != LBModeHybrid {
		return Config{}, fmt.Errorf("Invalid value for --%s: %s", LoadBalancerModeName, cfg.LBMode)
	}

	if cfg.LBModeAnnotation &&
		cfg.LBMode == LBModeHybrid {
		return Config{}, fmt.Errorf("The value --%s=%s is not supported as default under annotation mode", LoadBalancerModeName, cfg.LBMode)
	}

	if cfg.ReflectorWaitTime <= 0 {
		return Config{}, fmt.Errorf("--lb-reflector-wait-time must be greater than 0, got %s", cfg.ReflectorWaitTime)
	}

	if cfg.DSRDispatch != DSRDispatchOption &&
		cfg.DSRDispatch != DSRDispatchIPIP &&
		cfg.DSRDispatch != DSRDispatchGeneve {
		return Config{}, fmt.Errorf("Invalid value for --%s: %s", LoadBalancerDSRDispatchName, cfg.DSRDispatch)
	}

	return
}

var DefaultUserConfig = UserConfig{
	RetryBackoffMin:           time.Second,
	RetryBackoffMax:           time.Minute,

View on GitHub (pinned to ac7b90affa)

Solutions

Change the default --lb-mode to "snat" or "dsr" when annotation mode is enabled.
Disable the annotation mode option if hybrid as a cluster-wide default is required.
Use per-service annotations to select hybrid behavior where needed instead of a hybrid default.

Example fix

// before
--enable-lb-mode-annotation --lb-mode=hybrid
// after
--enable-lb-mode-annotation --lb-mode=snat

Defensive patterns

Strategy: validation

Validate before calling

if cfg.LBModeAnnotation && cfg.LBMode == loadbalancer.LBModeHybrid {
    return fmt.Errorf("hybrid default is incompatible with lb-mode annotation mode")
}

Try / catch

cfg, err := loadbalancer.NewConfig(log, uc, dcfg)
if err != nil && strings.Contains(err.Error(), "annotation mode") {
    uc.LBMode = loadbalancer.LBModeSNAT
    cfg, err = loadbalancer.NewConfig(log, uc, dcfg)
}

Prevention

Whenever enabling LBModeAnnotation, explicitly set a non-hybrid default mode.
Encode this pairing rule in Helm values validation or admission logic.
Add a unit test covering the annotation+hybrid combination.

When it happens

Trigger: Calling NewConfig with UserConfig.LBModeAnnotation == true AND LBMode == LBModeHybrid.

Common situations: Operators enabling the lb-mode annotation feature while keeping a previously-set default of hybrid; Helm/config templates that enable annotations without changing an inherited hybrid default.

Related errors

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