How to fix clusterrole.rbac.authorization.k8s.io "rolename" not found in Kubernetes

KubernetesINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 111 views

ClusterRole not found errors occur when a ClusterRoleBinding references a ClusterRole that does not exist or has been deleted. This is typically caused by creation order issues, typos in role names, or attempting to reference cluster roles across namespaces incorrectly.

Quick fix

Fixes clusterrole.rbac.authorization.k8s.io "rolename" not found

kubectl get clusterroles
kubectl get clusterrole <role-name>
  1. Verify the ClusterRole exists
  2. Check ClusterRole name spelling and exact match
  3. Create the ClusterRole before the binding
  4. Use describe to view ClusterRoleBinding details
kubernetes — error
kubectl get clusterroles
kubectl get clusterrole <role-name>
clusterrole.rbac.authorization.k8s.io "rolename" not found

What this error means

The "ClusterRole not found" error occurs when Kubernetes cannot locate a ClusterRole resource that is being referenced by a ClusterRoleBinding or when attempting to access cluster role resources without proper RBAC permissions. ClusterRole is a cluster-scoped RBAC resource that defines a set of permissions applicable across all namespaces. When you create a ClusterRoleBinding, it must reference an existing ClusterRole by exact name. If the referenced ClusterRole doesn't exist, has a different name, or was deleted, Kubernetes cannot establish the role binding. The error typically appears during deployment, when applying RBAC configuration files, or when attempting to list/describe cluster roles without sufficient permissions. The root cause is usually a mismatch between what the binding expects and what actually exists in the cluster.

Typical symptoms

  • ClusterRoleBinding creation fails with "ClusterRole not found" error
  • kubectl apply returns error about missing clusterrole.rbac.authorization.k8s.io
  • Pod or user permissions don't apply even after creating RBAC resources
  • Error appears when attempting to list cluster roles without admin permissions
  • kubectl describe clusterrolebinding shows reference to non-existent ClusterRole
  • Deployment manifests fail during helm install or kubectl apply
  • Service account cannot access resources even with binding present

Common causes

  1. ClusterRole is created after the ClusterRoleBinding that references it (wrong creation order)
  2. Typo or mismatch in ClusterRole name between definition and binding reference
  3. ClusterRole was deleted but ClusterRoleBinding still references it
  4. Applying manifests to wrong cluster where the ClusterRole doesn't exist
  5. User lacks RBAC permissions to list or describe cluster roles (forbidden error masquerading as not found)
  6. ClusterRole exists in a different cluster-context than where the binding is being applied
  7. Using Role instead of ClusterRole in namespace-scoped bindings

How to fix "clusterrole.rbac.authorization.k8s.io "rolename" not found"

1Verify the ClusterRole exists

List all available ClusterRoles in your cluster to confirm the role exists:

bash
kubectl get clusterroles
kubectl get clusterrole <role-name>

If you get "not found", the ClusterRole doesn't exist. If you get a "forbidden" error, your current user lacks permissions to list cluster roles.

2Check ClusterRole name spelling and exact match

Verify that your ClusterRoleBinding references the ClusterRole with the exact correct name:

yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: my-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: my-cluster-role  # Must match exactly
subjects:
- kind: ServiceAccount
  name: my-sa
  namespace: default

The roleRef.name must exactly match a ClusterRole's metadata.name. Check for trailing spaces, case sensitivity, and special characters.

3Create the ClusterRole before the binding

Ensure ClusterRole exists before creating ClusterRoleBinding. Apply in this order:

bash
# Step 1: Create the ClusterRole
kubectl apply -f clusterrole.yaml

# Step 2: Create the ClusterRoleBinding
kubectl apply -f clusterrolebinding.yaml

Or combine in a single file but define the ClusterRole before the ClusterRoleBinding.

4Use describe to view ClusterRoleBinding details

Inspect the ClusterRoleBinding to see what role it's trying to reference:

bash
kubectl describe clusterrolebinding <binding-name>

Look at the "RoleRef" section to confirm it shows the correct role name. Then verify that ClusterRole exists:

bash
kubectl get clusterrole <name-from-roleref>
5Verify you're targeting the correct cluster and context

If applying manifests across multiple clusters, ensure you're using the correct context:

bash
# List available contexts
kubectl config get-contexts

# Switch to the correct context
kubectl config use-context <context-name>

# Verify the cluster
kubectl cluster-info

Different clusters may have different ClusterRoles. The role must exist in the cluster where you're applying the binding.

6Check if you're accidentally using Role instead of ClusterRole

A common mistake is mixing Role (namespace-scoped) with ClusterRoleBinding. If your binding references a "Role" in kind but uses kind: ClusterRole in roleRef, Kubernetes will reject it:

yaml
# WRONG: Role with ClusterRoleBinding
kind: ClusterRoleBinding
roleRef:
  kind: Role  # Wrong! ClusterRoleBinding must reference ClusterRole
  name: my-role

Fix by ensuring roleRef.kind matches the actual resource type:

yaml
# Correct: ClusterRole with ClusterRoleBinding
kind: ClusterRoleBinding
roleRef:
  kind: ClusterRole  # Correct
  name: my-cluster-role
7Inspect manifest YAML for hidden characters or encoding issues

YAML encoding issues or hidden characters can cause name mismatches:

bash
# View the raw manifest to check for hidden characters
cat -A clusterrolebinding.yaml | grep roleRef -A 3

# Try creating with explicit name quotes

If using configuration management tools (Helm, Kustomize), verify template rendering:

bash
# For Helm
helm template my-release my-chart -f values.yaml | grep -A 5 roleRef

# For Kustomize
kustomize build . | grep -A 5 roleRef

Advanced notes

The ClusterRole not found error can be tricky because Kubernetes also returns similar errors when a user lacks RBAC permissions to list or describe cluster roles. If you're an admin and still see "forbidden", the binding exists but references a non-existent role. If you're a regular user, you might see "forbidden" instead of "not found" due to security considerations.

In CI/CD environments like ArgoCD or Flux CD, ensure ClusterRoles are created in a separate phase before ClusterRoleBindings. Many GitOps tools support kustomize ordering or allow explicit Helm chart ordering to enforce this dependency.

When using Helm charts, the chart templates must create ClusterRole resources before ClusterRoleBinding ones. Check the chart's templates/ directory to ensure correct ordering, or use Helm's hooks and weights to control deployment order.

For multi-cluster deployments, audit scripts should verify ClusterRole existence before attempting to create bindings. Use "get" with --ignore-not-found=false to fail fast if the role is missing.

Frequently asked questions

What does "clusterrole.rbac.authorization.k8s.io "rolename" not found" mean?
The "ClusterRole not found" error occurs when Kubernetes cannot locate a ClusterRole resource that is being referenced by a ClusterRoleBinding or when attempting to access cluster role resources without proper RBAC permissions. ClusterRole is a cluster-scoped RBAC resource that defines a set of permissions applicable across all namespaces. When you create a ClusterRoleBinding, it must reference an existing ClusterRole by exact name.
How do I fix "clusterrole.rbac.authorization.k8s.io "rolename" not found"?
ClusterRole not found errors occur when a ClusterRoleBinding references a ClusterRole that does not exist or has been deleted. This is typically caused by creation order issues, typos in role names, or attempting to reference cluster roles across namespaces incorrectly.
What causes "clusterrole.rbac.authorization.k8s.io "rolename" not found"?
ClusterRole is created after the ClusterRoleBinding that references it (wrong creation order) Typo or mismatch in ClusterRole name between definition and binding reference ClusterRole was deleted but ClusterRoleBinding still references it
Is the "clusterrole.rbac.authorization.k8s.io "rolename" not found" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading