cilium/cilium · error

failed to validate Listener (%w): %s

Error message

failed to validate Listener (%w): %s

What it means

When the validate flag is set (parsing of new, not-yet-applied resources), ParseResources calls listener.Validate() — the envoy protobuf validate (PGV) method enforcing Envoy constraints such as required address, filter config validity, and SO_REUSEPORT rules for BPF TPROXY mode. Any PGV failure is wrapped as 'failed to validate Listener (...)' together with the full listener proto string for debugging.

Source

Thrown at pkg/ciliumenvoyconfig/cec_resource_parser.go:315

						}
					}
					break // Done with this filter chain
				}
			}

			name := listener.Name
			listener.Name, _ = api.ResourceQualifiedName(cecNamespace, cecName, listener.Name, api.ForceNamespace)

			// Check for duplicate after the name has been qualified
			for i := range resources.Listeners {
				if listener.Name == resources.Listeners[i].Name {
					return xds.Resources{}, fmt.Errorf("duplicate Listener name %q", listener.Name)
				}
			}

			if validate {
				if err := listener.Validate(); err != nil {
					return xds.Resources{}, fmt.Errorf("failed to validate Listener (%w): %s", err, listener.String())
				}
			}
			resources.Listeners[listener.Name] = listener

			r.logger.Debug("ParseResources: Parsed listener",
				logfields.Name, name,
				logfields.Listener, listener)

		case envoy.RouteTypeURL:
			route, ok := message.(*envoy_config_route.RouteConfiguration)
			if !ok {
				return xds.Resources{}, fmt.Errorf("invalid type for Route: %T", message)
			}
			// Check that a Route name is provided
			if route.Name == "" {
				return xds.Resources{}, fmt.Errorf("unspecified RouteConfiguration name")
			}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Read the wrapped (%w) inner validation error and the listener string in the message to see the exact violated field; fix that field in the CEC.
2. Ensure required listener fields (name, address or internal_listener, filter chains) are present and well-formed.
3. If using BPF TPROXY (enableBPFTProxy), either mark the listener internal or let the parser disable reuse_port; do not set EnableReusePort=true on a socket-binding listener.
4. Align the envoy config dependency versions with the Cilium version so validation proto rules match.
5. Run the CEC through CiliumEnvoyConfigValidation-style checks locally before applying.

Example fix

// before
listener := &envoy_config_listener.Listener{Name: "x"} // no address, no filter chains
// after
listener := &envoy_config_listener.Listener{Name: "x", Address: socketAddr, FilterChains: chains}

for _, l := range cec.Listeners {
	msg := toListenerProto(l)
	if err := msg.Validate(); err != nil {
		return fmt.Errorf("listener %q fails envoy validation: %w", l.Name, err)
	}
}

res, err := parser.ParseResources(ns, name, xdsResources, inject, logger, validate, hdrs)
if err != nil {
	var verr error
	if errors.As(err, &verr) && strings.HasPrefix(err.Error(), "failed to validate Listener") {
		// parse inner %w validation error and listener string from message to fix config
	}
	return err
}

When it happens

Trigger: Calling ParseResources (with newResources=true) on a Listener that violates envoy protobuf validation: e.g. empty required fields, invalid filter chain config, or reuse_port enabled on a non-internal listener while enableBPFTProxy is active with mismatched settings.

Common situations: Invalid CiliumEnvoyConfig submitted by a user (missing address, malformed filter typed config), Envoy API version drift making fields invalid, or SO_REUSEPORT incompatibility when BPF TPROXY is enabled.

Related errors

• failed to validate RouteConfiguration (%w): %s
• invalid xDS mode %q
• must not be empty
• must not be more than 32 characters
• must consist of lower case alphanumeric characters and '-',

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