kubernetes/kubernetes · error

controllerRef.Controller is not set to true

Error message

controllerRef.Controller is not set to true

What it means

validateControllerRef rejects an OwnerReference where Controller is nil or set to false. The Controller boolean must be true to indicate that this owner is the managing controller of the pod. Kubernetes allows at most one OwnerReference with Controller=true per object. Setting it to false or nil would make this a non-controlling reference, which is invalid for the pod creation path.

Source

Thrown at pkg/controller/controller_utils.go:532

	prefix := fmt.Sprintf("%s-", controllerName)
	if len(validation.ValidatePodName(prefix, true)) != 0 {
		prefix = controllerName
	}
	return prefix
}

func validateControllerRef(controllerRef *metav1.OwnerReference) error {
	if controllerRef == nil {
		return fmt.Errorf("controllerRef is nil")
	}
	if len(controllerRef.APIVersion) == 0 {
		return fmt.Errorf("controllerRef has empty APIVersion")
	}
	if len(controllerRef.Kind) == 0 {
		return fmt.Errorf("controllerRef has empty Kind")
	}
	if controllerRef.Controller == nil || !*controllerRef.Controller {
		return fmt.Errorf("controllerRef.Controller is not set to true")
	}
	if controllerRef.BlockOwnerDeletion == nil || !*controllerRef.BlockOwnerDeletion {
		return fmt.Errorf("controllerRef.BlockOwnerDeletion is not set")
	}
	return nil
}

func (r RealPodControl) CreatePods(ctx context.Context, namespace string, template *v1.PodTemplateSpec, controllerObject runtime.Object, controllerRef *metav1.OwnerReference) error {
	return r.CreatePodsWithGenerateName(ctx, namespace, template, controllerObject, controllerRef, "")
}

func (r RealPodControl) CreatePodsWithGenerateName(ctx context.Context, namespace string, template *v1.PodTemplateSpec, controllerObject runtime.Object, controllerRef *metav1.OwnerReference, generateName string) error {
	if err := validateControllerRef(controllerRef); err != nil {
		return err
	}
	pod, err := GetPodFromTemplate(template, controllerObject, controllerRef)
	if err != nil {
		return err

View on GitHub (pinned to 94c1367642)

Solutions

1. Set Controller: pointer.Bool(true) on the OwnerReference.
2. Use metav1.NewControllerRef which sets Controller=true automatically.
3. Review any code that modifies controllerRef.Controller after construction.

Example fix

// before
controllerRef := &metav1.OwnerReference{
    APIVersion: "apps/v1",
    Kind: "StatefulSet",
    Name: setName,
    UID: set.UID,
}

// after
controllerRef := &metav1.OwnerReference{
    APIVersion: "apps/v1",
    Kind: "StatefulSet",
    Name: setName,
    UID: set.UID,
    Controller: pointer.Bool(true),
    BlockOwnerDeletion: pointer.Bool(true),
}

if controllerRef != nil && (controllerRef.Controller == nil || !*controllerRef.Controller) {
    return fmt.Errorf("controllerRef.Controller must be true")
}

When it happens

Trigger: RealPodControl.CreatePodsWithGenerateName validates controllerRef.Controller. The check is: controllerRef.Controller == nil || !*controllerRef.Controller. A controllerRef with Controller unset or explicitly false triggers this.

Common situations: Manually building an OwnerReference and forgetting to set Controller: pointer.Bool(true). Using a non-controlling OwnerReference (e.g., for metadata linking) where a controlling one was expected. Refactoring that drops the Controller field.

Related errors

• controllerRef is nil
• controllerRef has empty APIVersion
• controllerRef has empty Kind
• controllerRef.BlockOwnerDeletion is not set
• unable to create pods, no labels

AI-assisted analysis of kubernetes/kubernetes@94c1367642 (2026-08-08). Data as JSON: /api/errors/417317afb9f29c25. Report an issue: GitHub.