What causes "failed to setup Envoy load balancer reconciler: %w" in cilium/cilium?

Verify the CiliumEnvoyConfig CRD is installed: kubectl get crd ciliumenvoyconfigs.cilium.io; if missing, apply the CRDs from the matching Cilium version

cilium/cilium · critical

failed to setup Envoy load balancer reconciler: %w

Error message

failed to setup Envoy load balancer reconciler: %w

What it means

During operator startup, registerL7LoadBalancingController builds an Envoy load balancer reconciler and registers it with the controller-runtime manager via SetupWithManager. If registration fails (controller builder errors, missing Scheme registration, or watch setup problems), startup of the L7 load-balancing controller aborts with this wrapped error.

Source

Thrown at operator/pkg/ciliumenvoyconfig/cell.go:100

		return nil
	}

	params.Logger.Info("Register Envoy load balancer reconciler")

	reconciler := newCiliumEnvoyConfigReconciler(
		params.CtrlRuntimeManager.GetClient(),
		params.Logger,
		params.Config.LoadBalancerL7Algorithm,
		params.Config.LoadBalancerL7Ports,
		10,
		params.ProxyTimeouts.ProxyIdleTimeoutSeconds,
		params.ProxyTimeouts.ProxyStreamIdleTimeoutSeconds,
		agentOption.Config.EnableIPv4,
		agentOption.Config.EnableIPv6,
	)

	if err := reconciler.SetupWithManager(params.CtrlRuntimeManager); err != nil {
		return fmt.Errorf("failed to setup Envoy load balancer reconciler: %w", err)
	}

	return nil
}

View on GitHub (pinned to ac7b90affa)

Solutions

Verify the CiliumEnvoyConfig CRD is installed: kubectl get crd ciliumenvoyconfigs.cilium.io; if missing, apply the CRDs from the matching Cilium version
Check the wrapped cause in the startup error for scheme/watch specifics
Ensure the manager Scheme includes ciliumv2 types (correct cell wiring/registration)
Confirm RBAC allows the operator to list/watch CiliumEnvoyConfigs

Defensive patterns

Strategy: try-catch

Validate before calling

// before startup, verify the CRD and RBAC are in place
_, err := discoveryClient.ServerResourcesForGroupVersion("cilium.io/v2")
if err != nil {
    return fmt.Errorf("CiliumEnvoyConfig CRD not available: %w", err)
}

Try / catch

if err := reconciler.SetupWithManager(params.CtrlRuntimeManager); err != nil {
    log.Fatal("L7 LB controller registration failed",
        "cause", errors.Unwrap(err),
        "hint", "check CRDs installed and scheme registration")
}

Prevention

Apply Cilium CRDs for the exact operator version before starting the operator
Register ciliumv2 types in the controller-runtime Scheme during cell wiring
Grant list/watch RBAC on ciliumenvoyconfigs to the operator ServiceAccount
Test operator startup in CI against a cluster with CRDs applied

When it happens

Trigger: SetupWithManager returns an error: CiliumEnvoyConfig types not registered in the manager Scheme, the ciliumenvoyconfigs CRD does not exist in the cluster, or the controller builder cannot set up watches/informer caches for the watched resource types.

Common situations: Cluster missing the cilium.io CiliumEnvoyConfig CRD (CRDs not applied/upgraded); operator cell wiring missing ciliumv2 Scheme registration; RBAC preventing cache sync for watched resources; controller-runtime version incompatibilities.

Related errors

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