> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/kubernetes-hosted/troubleshooting-the-acecloud-kubectl-auth-plugin.md). # Troubleshooting the AceCloud kubectl Auth Plugin ## Overview The AceCloud kubectl Auth Plugin enables kubectl to authenticate with your AceCloud Kubernetes cluster using the credentials provided through the AceCloud portal. If a kubectl command does not work as expected, identify the error message or symptom below and follow the corresponding troubleshooting steps. ## Contents * [How to read a session-expired message](#how-to-read-a-session-expired-message) * ["Your session has expired"](#your-session-has-expired) * ["No refresh token available"](#no-refresh-token-available) * ["command not found: kubectl-acecloud\_auth"](#command-not-found-kubectl-acecloud_auth) * ["HTTP request failed" or Timeout](#http-request-failed-or-timeout) * [AceCloud Portal Temporarily Unavailable](#acecloud-portal-temporarily-unavailable) * [Installer Is Stuck or Fails During Download](#installer-is-stuck-or-fails-during-download) * [kubectl Does Not Appear to Be Using the Plugin](#kubectl-does-not-appear-to-be-using-the-plugin) * ["Forbidden"](#forbidden) * ["You must be logged in to the server (Unauthorized)"](#you-must-be-logged-in-to-the-server-unauthorized) * ["certificate signed by unknown authority"](#certificate-signed-by-unknown-authority) * [Clear the Plugin Cache](#clear-the-plugin-cache) * [Still Facing the Issue?](#still-facing-the-issue) ## How to read a session-expired message When the plugin can't get a valid credential, it prints two lines: ``` Error: token refresh failed: server returned HTTP 401: ... ``` ``` Your session has expired. Please download a fresh kubeconfig from the AceCloud portal. ``` The second line is always the same general suggestion, regardless of the actual cause. The first line starting with *token refresh failed*: is what tells you what's actually happening. Use it to find the right section below: | **First line contains** | **Go to** | | ------------------------------------------------ | --------------------------------------- | | HTTP 401 | "Your session has expired" | | A connection error, timeout, or unreachable host | "HTTP request failed" or Timeout | | HTTP 502, 503, 500, or an empty/missing token | AceCloud Portal Temporarily Unavailable | | no refresh token available | "No refresh token available" | ## "Your session has expired" ### Error ``` Your session has expired. Please download a fresh kubeconfig from the AceCloud portal. ``` ### Cause The access credential associated with the KubeConfig is no longer valid. This can occur when: * The credential has reached its 30-day validity period. * The credential has not been used for 7 days. * An administrator has revoked the user's access. * **The same KubeConfig is being used by more than one user, script, or machine.** The AceCloud authentication plugin automatically renews credentials, and each renewal retires the previous one-time-use token and issues a new one. If the same KubeConfig is shared, whichever client renews first invalidates the token every other client was using so the next kubectl command from anywhere else fails with this same message. This typically shows up as kubectl working for one user but suddenly failing for another, or failing right after a teammate ran a command. * **A new KubeConfig was downloaded and used elsewhere.** Downloading a KubeConfig doesn't invalidate anything by itself invalidation happens the moment the new KubeConfig is actually used, since that first refresh replaces the shared credential and retires every older copy. This is the same underlying mechanism as sharing a KubeConfig, above: whichever copy refreshes first "wins." ### Resolution **If the credential simply expired or was revoked:** 1. Log in to the AceCloud portal. 2. Download a new KubeConfig for the required cluster. 3. Use the newly downloaded KubeConfig with kubectl. **Note:** An expired credential cannot be restored. Downloading a fresh KubeConfig is the expected resolution. **If the same KubeConfig is shared across users, machines, or a new one was downloaded elsewhere:** * Each user should log in to the AceCloud portal and use their own KubeConfig never a shared copy. * For CI/CD pipelines, automation scripts, shared systems, or service-based workloads, do not use a personal KubeConfig. Use a dedicated Kubernetes service account with its own credentials instead. This prevents credential-refresh conflicts between users and automated processes. * If you know a new KubeConfig was downloaded and used elsewhere recently, use the newest one everywhere it's needed going forward. ## "No refresh token available" ### Cause The KubeConfig being used by kubectl does not contain a valid access credential. This can happen if the KubeConfig was: * Manually edited. * Generated through a method other than the AceCloud portal. * Modified after it was downloaded. ### Resolution Download a fresh KubeConfig from the AceCloud portal and use it instead of manually modifying the existing file. ## "command not found: kubectl-acecloud\_auth" ### Error ``` command not found: kubectl-acecloud_auth ``` or ``` exec: executable kubectl-acecloud_auth not found ``` ### Cause The AceCloud kubectl Auth Plugin may not be installed, or the terminal may not have the plugin's installation path available. ### Resolution 1. Open a new terminal window and run the kubectl command again. A new terminal typically loads the plugin's installation path automatically. 2. If the issue persists, verify whether the plugin is installed: * Linux/macOS: which kubectl-acecloud\_auth * Windows (PowerShell): Get-Command kubectl-acecloud\_auth 3. If the command returns no result, reinstall the plugin by following the [Installing and Setting Up the AceCloud kubectl Auth Plugin](https://docs.acecloud.ai/knowledge-base/kubernetes-hosted/installing-and-setting-up-the-acecloud-kubectl-auth-plugin) procedure. 4. If you installed the plugin and want to use it in the same terminal session, run the source command displayed by the installer at the end of the installation process. ## "HTTP request failed" or Timeout ### Cause The AceCloud authentication plugin cannot establish a connection with the AceCloud portal. Your credential itself is fine this is a connectivity issue, not a session problem, even though the on-screen message may suggest otherwise. ### Resolution Check the following in order: 1. Verify that your internet connection is working. 2. Connect to your organization's VPN, if VPN access is required to reach the AceCloud portal. 3. On guest or hotel Wi-Fi, open a browser and complete any network sign-in page first this is a common, easily missed cause. 4. Contact your network or IT team to verify whether a firewall or network policy is blocking the connection. ## AceCloud Portal Temporarily Unavailable ### Cause Your credential and your connection are both fine the AceCloud portal's authentication service is briefly unable to respond. ### Resolution 1. Wait a few minutes and try again. 2. Do not download a new KubeConfig it will not help, and it will invalidate the one you already have. 3. If the issue continues for more than a few minutes, contact AceCloud Support with the exact error message. ## Installer Is Stuck or Fails During Download ### Cause The installer may be unable to download the required files because: * The network connection is unstable or slow. * A corporate proxy or firewall is blocking one of the download sources. * GitHub release-download domains are restricted by your organization's network policy. ### Resolution 1. Verify your internet connection. 2. Connect to your VPN, if required. 3. If you are using a corporate network, contact your IT team and ask them to verify that GitHub release-download domains are permitted through the organization's firewall or proxy. 4. Run the installer again. **Note:** The installer automatically retries several times when temporary network failures occur before terminating the installation. ## kubectl Does Not Appear to Be Using the Plugin ### Cause kubectl may be using a different KubeConfig or context, or the AceCloud authentication plugin may not be installed correctly. ### Resolution 1. Check the currently active Kubernetes context: kubectl config current-context 2. Verify that the AceCloud authentication plugin is installed and available in your system path. 3. If you merged the AceCloud KubeConfig with an existing KubeConfig, switch to the correct AceCloud context: kubectl config use-context \ 4. Run the required kubectl command again. ## "Forbidden" ### Error ``` Error from server (Forbidden): pods is forbidden: User "you@acecloud.ai" cannot list resource "pods" in API group "" in the namespace "default" ``` ### Cause Authentication has already succeeded the cluster knows exactly who you are but your account does not have permission for that action or in that namespace. This is not a plugin or sign-in issue. ### Resolution Contact your organization's administrator and request the access you need. Re-downloading your KubeConfig, reinstalling the plugin, or clearing the cache will have no effect, since nothing is wrong with your sign-in. ## "You must be logged in to the server (Unauthorized)" ### Error ``` error: You must be logged in to the server (Unauthorized) ``` ### Cause The cluster rejected an otherwise valid credential. The most common cause is that your computer's clock is incorrect credentials are time-limited, and a clock off by more than a couple of minutes can make a valid credential unusable. ### Resolution 1. Check your system clock and time zone, and enable automatic time synchronization. 2. Try the command again. 3. If the clock is correct and the issue persists, contact AceCloud Support this may indicate a cluster-side configuration issue. ## "certificate signed by unknown authority" ### Error ``` Unable to connect to the server: x509: certificate signed by unknown authority ``` ### Cause A certificate problem while reaching the cluster, unrelated to sign-in. Often caused by a corporate network inspecting traffic, or an edited KubeConfig. ### Resolution 1. Download a fresh KubeConfig from the AceCloud portal. 2. If the issue persists, check with your IT team whether traffic to the cluster is being intercepted. ## Clear the Plugin Cache If the plugin appears to be stuck, or you suspect a locally cached credential is outdated, clear the plugin cache. Run: ``` kubectl-acecloud_auth clear-cache ``` After clearing the cache, run any kubectl command again. The plugin automatically requests a new credential. **Note:** Clearing the plugin cache is safe and can be used when troubleshooting unexpected authentication behavior. It does not fix an expired credential and does not require downloading a new KubeConfig. ## Still Facing the Issue? If the issue persists after following the troubleshooting steps above, contact AceCloud Support and provide the following information: * The complete error message displayed in the terminal, including the token refresh failed: ... line, not just the last sentence. * The output of: kubectl acecloud\_auth version * The cluster name. * The approximate date and time when the issue occurred. * Whether the KubeConfig is used anywhere else another machine, a script, or a colleague. Providing this information helps the support team diagnose the authentication issue more efficiently.