Unauthorized
This error occurs when the API server rejects a request due to missing, invalid, or expired authentication credentials.
Usually happens because:
- ☑ Temporary cloud provider CLI session access token has expired
- ☑ Kubeconfig user settings reference stale credentials helper configurations
- ☑ Clock drift on cluster nodes causes identity token invalidations
🔍 Quick Checklist:
What is Unauthorized?
An 'Unauthorized' (HTTP 401) error is returned by the Kubernetes API server when the client request fails authentication checks. In Kubernetes v1.36 clusters, this indicates that the provided Bearer token, client certificate, or OIDC login token is either malformed, expired, or has not been recognized by the configured authentication provider (like AWS IAM authenticator, GCP auth helper, or OpenID Connect provider).
Common Causes
- Expired cloud token: The temporary IAM credentials token (e.g. from AWS ECR/EKS or Google GKE) has expired (default limit is usually 15 minutes to 1 hour).
- Incorrect Kubeconfig credentials mapping: The kubeconfig references a wrong client cert key or points to an outdated token file path.
- OIDC integration configuration drift: The OpenID Connect token is rejected because the API server flags or local clock times are out of sync with the identity provider.
| Cause | Frequency |
|---|---|
| Expired cloud provider access token (timeout exceeded) | ⭐⭐⭐⭐⭐ |
| Stale or misconfigured credential files in user's home folder | ⭐⭐⭐⭐ |
| OIDC identity provider token verification failure (clock drift) | ⭐⭐⭐ |
Common Mistakes
- Running `kubectl` inside scripts using static hardcoded tokens that were generated temporarily, failing once the token lease duration lapses.
- Mismatched context names inside kubeconfig where client usernames point to wrong cluster endpoints.
How to Fix
Kubernetes Operations & Verification
Examine user token credential helpers definitions inside the kubeconfig users array configuration.
apiVersion: v1
kind: Config
users:
- name: developer-user
user:
# 1. AWS IAM Authenticator helper block
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: aws
args:
- "eks"
- "get-token"
- "--cluster-name"
- "production-cluster"Platform Specific Fixes
Inspect API server logs to track token authentication reject events.
# Read API server logs filtering by authentication faults
journalctl -u kube-apiserver -n 50 | grep -i "authentication failed"Best Practices
- Always rely on dynamic CLI credential helper plugins (`exec` auth) rather than copy-pasting static bearer tokens.
- Synchronize cluster nodes using reliable time sync clients (like chrony or systemd-timesyncd).
Frequently Asked Questions (FAQ)
Q: What is the difference between Unauthorized and Forbidden?
Unauthorized (HTTP 401) means the API server does not know who you are (your credentials are missing or expired). Forbidden (HTTP 403) means you are successfully authenticated, but you do not have RBAC permissions to perform the requested action.
Q: How do I fix 'Unauthorized' when running kubectl commands?
This is almost always due to an expired session token. If you are on a cloud-managed Kubernetes cluster (EKS, GKE, AKS), run the cloud CLI login commands again to refresh your token.
Q: Why does clock drift cause this error?
OIDC tokens contain a 'not before' (nbf) and 'expiration' (exp) timestamp. If the clocks on your worker nodes or local machine drift by even a few minutes compared to the OIDC provider, the API server will reject the token as invalid or not yet active.
Q: How do I troubleshoot webhook authentication failures?
If you use Webhook Token Authentication, the API server sends a TokenReview request to the webhook. Ensure the webhook server is reachable and configured with the correct shared keys.