How to fix Unauthorized in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 215 views

The "Unauthorized" error in Kubernetes indicates that authentication to the API server has failed, usually because your credentials are missing, invalid, or expired. This is different from "Forbidden" which means you're authenticated but lack permissions.

Quick fix

Fixes Unauthorized

aws eks update-kubeconfig --name <cluster-name> --region <region>
  1. Refresh kubeconfig for cloud-managed Kubernetes
  2. Check your current Kubernetes context and user
  3. Verify client certificates exist and are valid
  4. Add IAM user to aws-auth ConfigMap (EKS only)
kubernetes — error
aws eks update-kubeconfig --name <cluster-name> --region <region>
Unauthorized

What this error means

An Unauthorized error (HTTP 401) from Kubernetes means the API server rejected your credentials. This happens at the authentication layer, before permission checks. Common causes include expired tokens, invalid certificate data in kubeconfig, missing IAM credentials on cloud platforms, or stale service account tokens. The error prevents you from communicating with the cluster at all—no kubectl commands work. Unlike Forbidden (403), which means you're logged in but don't have permission for a specific action, Unauthorized means the server doesn't even know who you are.

Typical symptoms

  • kubectl commands fail with "You must be logged in to the server (Unauthorized)"
  • All API requests return HTTP 401 Unauthorized
  • Kubernetes Dashboard requires repeated sign-ins or rejects credentials
  • CI/CD pipelines fail at deployment stage with authentication errors
  • Service-to-service communication fails due to invalid tokens
  • kubectl works locally but fails in containerized environments or other machines

Common causes

  1. Expired or invalid bearer token in kubeconfig—tokens are short-lived and don't auto-refresh without OIDC setup
  2. Misconfigured kubeconfig with invalid certificate paths or outdated certificate-data values
  3. Missing or incorrect IAM credentials on managed Kubernetes (AWS EKS, Azure AKS, GCP GKE)
  4. Service account token improperly copied (not base64 decoded) or associated with a service account lacking roles
  5. Expired client certificates in kubeconfig after Kubernetes certificate renewal
  6. IAM principal not mapped to cluster (EKS requires aws-auth ConfigMap entry)
  7. Wrong AWS IAM credentials in environment or kubeconfig for EKS clusters

How to fix "Unauthorized"

1Refresh kubeconfig for cloud-managed Kubernetes

Run the appropriate command for your platform:

AWS EKS:

bash
aws eks update-kubeconfig --name <cluster-name> --region <region>

Azure AKS:

bash
az aks get-credentials --name <cluster> --resource-group <group>

GCP GKE:

bash
gcloud container clusters get-credentials <cluster> --zone <zone>

This regenerates ~/.kube/config with fresh credentials. Test with kubectl get nodes.

2Check your current Kubernetes context and user

Run kubectl config current-context to see what cluster you're connected to. Run kubectl config view to inspect your entire kubeconfig. Look for:
- Valid server URL (not localhost unless using local cluster)
- Non-empty certificate-data or certificate file path
- Valid client-key-data or client-key file
- Correct user and context references

If any values are empty, incomplete, or point to missing files, that's your issue.

3Verify client certificates exist and are valid

Check certificate expiration:

bash
openssl x509 -in ~/.kube/<cert-file> -text -noout | grep -A2 "Validity"

If certificates are expired, regenerate kubeconfig:
- Local clusters (Minikube/Docker Desktop): Delete cluster and recreate
- Cloud clusters: Use the refresh command from Step 1
- Self-managed: Regenerate certificates on cluster control plane (check cluster docs)

4Add IAM user to aws-auth ConfigMap (EKS only)

For EKS clusters, the IAM user creating the cluster gets admin automatically. Other users need entries in aws-auth:

bash
kubectl edit -n kube-system configmap/aws-auth

Add your IAM user/role under mapUsers or mapRoles:

yaml
mapUsers: |
  - userarn: arn:aws:iam::ACCOUNT:user/USERNAME
    username: USERNAME
    groups:
      - system:masters
mapRoles: |
  - rolearn: arn:aws:iam::ACCOUNT:role/ROLENAME
    username: ROLENAME
    groups:
      - system:masters

Save and test: kubectl get nodes. Verify IAM credentials: aws sts get-caller-identity.

5Verify IAM credentials are valid

Check which AWS credentials kubectl is using:

bash
aws sts get-caller-identity

This shows the account, user, and ARN. Verify this matches your EKS cluster account and that the user/role has proper permissions. If credentials are wrong, set them:

bash
export AWS_ACCESS_KEY_ID=<your-key>
export AWS_SECRET_ACCESS_KEY=<your-secret>
export AWS_REGION=<your-region>

Or configure via ~/.aws/credentials and run aws configure.

6Fix service account token for pod-to-API communication

If a pod can't authenticate to the API server, verify the service account token:

bash
kubectl get sa -n <namespace>
kubectl describe sa <sa-name> -n <namespace>

Check the secret: kubectl get secret <secret-name> -n <namespace> -o yaml. The token must be base64-encoded. Mount it correctly in your pod:

yaml
spec:
  serviceAccountName: <sa-name>
  containers:
  - name: app
    volumeMounts:
    - name: token
      mountPath: /var/run/secrets/kubernetes.io/serviceaccount
  volumes:
  - name: token
    secret:
      secretName: <sa-name>-token
7Enable OIDC for automatic token refresh (advanced)

For long-lived sessions, configure OIDC token refresh in kubeconfig. This prevents token expiration:

yaml
apiVersion: v1
kind: Config
users:
- name: my-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws-iam-authenticator
      args:
        - token
        - -i
        - <cluster-name>

For other identity providers (Azure, GCP, etc.), check their documentation for OIDC configuration. This requires cluster-side setup—ask your cluster administrator.

Advanced notes

On AWS EKS, the IAM identity that created the cluster automatically gains admin access; other users must be explicitly added to aws-auth ConfigMap. Azure AKS uses Azure AD integration—verify Azure AD user exists and has correct role. GCP GKE uses Google Cloud IAM directly. For CI/CD systems (GitLab, GitHub Actions, Jenkins), service account tokens need explicit secret configuration and proper RBAC bindings. WSL2 environments may have credential caching issues between Windows and Linux—clear caches if credentials were rotated. When rotating IAM credentials, both old and new caches may need clearing: kubectl config unset users.<user-name> and aws sso logout. OpenID Connect providers require both client-side (kubeconfig) and server-side (cluster) configuration for token refresh to work. Certificate-based authentication doesn't auto-refresh—regenerate kubeconfig after certificate renewal.

Frequently asked questions

What does "Unauthorized" mean?
An Unauthorized error (HTTP 401) from Kubernetes means the API server rejected your credentials. This happens at the authentication layer, before permission checks. Common causes include expired tokens, invalid certificate data in kubeconfig, missing IAM credentials on cloud platforms, or stale service account tokens.
How do I fix "Unauthorized"?
The "Unauthorized" error in Kubernetes indicates that authentication to the API server has failed, usually because your credentials are missing, invalid, or expired. This is different from "Forbidden" which means you're authenticated but lack permissions.
What causes "Unauthorized"?
Expired or invalid bearer token in kubeconfig—tokens are short-lived and don't auto-refresh without OIDC setup Misconfigured kubeconfig with invalid certificate paths or outdated certificate-data values Missing or incorrect IAM credentials on managed Kubernetes (AWS EKS, Azure AKS, GCP GKE)
Is the "Unauthorized" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading