kubernetes/kops · critical

error creating Cluster controller: %w

Error message

error creating Cluster controller: %w

What it means

RegisterControllers is called at controller-manager startup (from main) to wire up the clusterapi controllers. This error wraps any failure returned by NewClusterReconciler when it tries to construct and register the Cluster reconciler with the controller-runtime manager — typically a manager setup failure (e.g. scheme registration or controller builder error), not a runtime reconcile failure.

Source

Thrown at pkg/controllers/clusterapi/register.go:32

limitations under the License.
*/

package clusterapi

import (
	"fmt"

	"k8s.io/kops/pkg/client/simple"
	"sigs.k8s.io/controller-runtime/pkg/manager"
)

func RegisterControllers(mgr manager.Manager, clientset simple.Clientset) error {
	if err := NewKopsConfigReconciler(mgr, clientset); err != nil {
		return fmt.Errorf("error creating KopsConfig controller: %w", err)
	}

	if err := NewClusterReconciler(mgr); err != nil {
		return fmt.Errorf("error creating Cluster controller: %w", err)
	}

	return nil
}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Inspect the wrapped cause (%w) in the error message to see the underlying NewClusterReconciler failure
2. Verify all required CRDs (Cluster, KopsConfig) are installed in the management cluster before starting the controller-manager
3. Ensure the manager's scheme registers the cluster-api and kops types the reconciler needs
4. Check controller-runtime and cluster-api dependency versions are compatible (go.mod / vendor)
5. Rebuild/redeploy the controller-manager after fixing the cause

Example fix

// before
if err := NewClusterReconciler(mgr); err != nil {
	return fmt.Errorf("error creating Cluster controller: %w", err)
}
// after
// ensure scheme includes required types before building the manager
scheme := runtime.NewScheme()
_ = clientgoscheme.AddToScheme(scheme)
_ = clusterv1.AddToScheme(scheme)
_ = kopsapi.AddToScheme(scheme)
mgr, err := manager.New(cfg, manager.Options{Scheme: scheme})
if err != nil {
	return fmt.Errorf("error creating manager: %w", err)
}
if err := NewClusterReconciler(mgr); err != nil {
	return fmt.Errorf("error creating Cluster controller: %w", err)
}

// before starting the controller manager, verify CRDs and scheme
for _, gvk := range []schema.GroupVersionKind{
	{Group: "cluster.x-k8s.io", Version: "v1beta1", Kind: "Cluster"},
	{Group: "kops.k8s.io", Version: "v1alpha2", Kind: "Cluster"},
} {
	if !mgr.GetScheme().Recognizes(gvk) {
		return fmt.Errorf("scheme does not recognize %v", gvk)
	}
}

func isRegistrationError(err error) bool {
	var agg utilerrors.Aggregate
	return errors.As(err, &agg) || strings.Contains(err.Error(), "error creating Cluster controller")
}

if err := RegisterControllers(mgr, clientset); err != nil {
	setupLog.Error(err, "failed to register clusterapi controllers; check CRDs are installed and scheme is complete")
	os.Exit(1) // fail fast: registration errors are not retryable at runtime
}

When it happens

Trigger: NewClusterReconciler(mgr) returns a non-nil error during RegisterControllers, which happens at process startup when main calls RegisterControllers(mgr, clientset); e.g. the controller builder cannot watch the Cluster resource or the manager's scheme lacks a required type.

Common situations: Starting `kops` controller-manager with a manager whose scheme is missing the Cluster CRD types, RBAC/CRD not installed so the watch cannot be set up, or an incompatible controller-runtime version breaking the builder call.

Related errors

• error creating KopsConfig controller: %w
• error building corev1 client: %v
• clientset is not initialized
• error registering corev1: %v
• error registering kops/v1alpha2 API: %v

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/39ef609686cb6a9d. Report an issue: GitHub.