{"record":{"id":"39ef609686cb6a9d","repo":"kubernetes/kops","slug":"error-creating-cluster-controller-w","errorCode":null,"errorMessage":"error creating Cluster controller: %w","messagePattern":"error creating Cluster controller: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/controllers/clusterapi/register.go","lineNumber":32,"sourceCode":"limitations under the License.\n*/\n\npackage clusterapi\n\nimport (\n\t\"fmt\"\n\n\t\"k8s.io/kops/pkg/client/simple\"\n\t\"sigs.k8s.io/controller-runtime/pkg/manager\"\n)\n\nfunc RegisterControllers(mgr manager.Manager, clientset simple.Clientset) error {\n\tif err := NewKopsConfigReconciler(mgr, clientset); err != nil {\n\t\treturn fmt.Errorf(\"error creating KopsConfig controller: %w\", err)\n\t}\n\n\tif err := NewClusterReconciler(mgr); err != nil {\n\t\treturn fmt.Errorf(\"error creating Cluster controller: %w\", err)\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":14,"sourceCodeEnd":37,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/controllers/clusterapi/register.go#L14-L37","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped cause (%w) in the error message to see the underlying NewClusterReconciler failure","Verify all required CRDs (Cluster, KopsConfig) are installed in the management cluster before starting the controller-manager","Ensure the manager's scheme registers the cluster-api and kops types the reconciler needs","Check controller-runtime and cluster-api dependency versions are compatible (go.mod / vendor)","Rebuild/redeploy the controller-manager after fixing the cause"],"exampleFix":"// before\nif err := NewClusterReconciler(mgr); err != nil {\n\treturn fmt.Errorf(\"error creating Cluster controller: %w\", err)\n}\n// after\n// ensure scheme includes required types before building the manager\nscheme := runtime.NewScheme()\n_ = clientgoscheme.AddToScheme(scheme)\n_ = clusterv1.AddToScheme(scheme)\n_ = kopsapi.AddToScheme(scheme)\nmgr, err := manager.New(cfg, manager.Options{Scheme: scheme})\nif err != nil {\n\treturn fmt.Errorf(\"error creating manager: %w\", err)\n}\nif err := NewClusterReconciler(mgr); err != nil {\n\treturn fmt.Errorf(\"error creating Cluster controller: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"// before starting the controller manager, verify CRDs and scheme\nfor _, gvk := range []schema.GroupVersionKind{\n\t{Group: \"cluster.x-k8s.io\", Version: \"v1beta1\", Kind: \"Cluster\"},\n\t{Group: \"kops.k8s.io\", Version: \"v1alpha2\", Kind: \"Cluster\"},\n} {\n\tif !mgr.GetScheme().Recognizes(gvk) {\n\t\treturn fmt.Errorf(\"scheme does not recognize %v\", gvk)\n\t}\n}","typeGuard":"func isRegistrationError(err error) bool {\n\tvar agg utilerrors.Aggregate\n\treturn errors.As(err, &agg) || strings.Contains(err.Error(), \"error creating Cluster controller\")\n}","tryCatchPattern":"if err := RegisterControllers(mgr, clientset); err != nil {\n\tsetupLog.Error(err, \"failed to register clusterapi controllers; check CRDs are installed and scheme is complete\")\n\tos.Exit(1) // fail fast: registration errors are not retryable at runtime\n}","preventionTips":["Install all required CRDs (cluster.x-k8s.io, kops.k8s.io) before launching the controller-manager","Register every needed type in the manager scheme before building controllers","Pin compatible controller-runtime / cluster-api versions in go.mod and run dependency upgrade tests","Add a startup smoke test that constructs the manager and calls RegisterControllers against envtest"],"tags":["controller-runtime","startup","kubernetes","controller-registration"],"backgroundTag":"controller-registration-failed","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}