cilium/cilium · error

ztunnel-endpoint-event-channel-buffer-size must be non-negat

Error message

ztunnel-endpoint-event-channel-buffer-size must be non-negative, got %d

What it means

Config.Validate enforces that the hidden tuning flag ztunnel-endpoint-event-channel-buffer-size is not negative. The value is a Go channel buffer size for endpoint events; a negative number is meaningless and would panic on channel creation downstream, so it is rejected during config validation with the offending value included.

Source

Thrown at pkg/ztunnel/config/config.go:33

}

// Config is a shared config for all ZTunnel module's cells.
// Note: The operator reads EnableZTunnel directly from the ConfigMap,
// while the agent uses this Config struct for dependency injection.
type Config struct {
	EnableZTunnel                  bool
	EndpointEventChannelBufferSize int `mapstructure:"ztunnel-endpoint-event-channel-buffer-size"`
}

func (c Config) Flags(flags *pflag.FlagSet) {
	flags.Bool("enable-ztunnel", false, "Use zTunnel as Cilium's encryption infrastructure")
	flags.Int("ztunnel-endpoint-event-channel-buffer-size", 1, "Buffer size for the ztunnel endpoint event channel")
	flags.MarkHidden("ztunnel-endpoint-event-channel-buffer-size")
}

func (c Config) Validate() error {
	if c.EndpointEventChannelBufferSize < 0 {
		return fmt.Errorf("ztunnel-endpoint-event-channel-buffer-size must be non-negative, got %d", c.EndpointEventChannelBufferSize)
	}
	return nil
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Set the flag to 0 or a positive integer (default is 1)
2. Remove the flag entirely to use the built-in default
3. Clamp the value in your deployment tooling: max(0, computedValue)
4. If '0' was intended to disable eventing, use the correct disable mechanism instead of -1

Example fix

// before
extraArgs: { ztunnel-endpoint-event-channel-buffer-size: "-1" }
// after
extraArgs: { ztunnel-endpoint-event-channel-buffer-size: "1" }

if buf, err := strconv.Atoi(flagVal); err != nil || buf < 0 {
    return fmt.Errorf("ztunnel-endpoint-event-channel-buffer-size must be >= 0, got %q", flagVal)
}

if err := cfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "buffer-size must be non-negative") {
        cfg.EndpointEventChannelBufferSize = 1 // fall back to default
    }
    return err
}

When it happens

Trigger: Starting the agent with --ztunnel-endpoint-event-channel-buffer-size set to a negative integer, typically via CLI flags, Helm extraArgs, or an environment/config file that interpolates an unvalidated value into the flag.

Common situations: Helm values computed from an expression that can go negative (e.g. subtracting from a small default); copy-paste of '-1' meant to 'disable' the channel; automation writing the flag from an unset env var defaulting oddly.

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

• must not be empty
• must not be more than 32 characters
• must consist of lower case alphanumeric characters and '-',
• lost event send interval must be greater than 0
• bad config

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