Jun 11, 2024

Kubectl command not found: causes and fixes

Diagnose kubectl command not found errors caused by missing installs, PATH issues, permissions, Docker state, or Minikube command syntax.

"kubectl: command not found" is not an interesting error. It is still enough to stop every debugging session cold. Fix the local toolchain first, then worry about the cluster.

The usual causes are boring: kubectl is not installed, it is not on PATH, permissions are wrong, Docker or Minikube is not running, or the Minikube wrapper command is malformed.

What causes the kubectl command not found issue?

There can be multiple reasons for the kubectl command not found issue. Before we dive into how to fix it, let's see what it looks like:

$ kubectl get pods

>> command not found: kubectl

Some of the common reasons you might run into this issue are:

• kubectl is not installed locally: One of the most frequent reasons command not found issues occur is that the tool is not installed; therefore, the terminal is unable to find it.
• Typo in the command name: If you accidentally made a mistake while typing kubectl, the terminal might not be able to identify the right tool and will then return a command not found error.
• Missing execution permissions on kubectl: Your terminal may not have execution permissions on the kubectl tool. In this case, it might not identify kubectl as an executable, and it won't know what to do when you use the kubectl command.
• Missing the kubectl tool in your system's PATH: Even if you ensure that kubectl is installed locally and you have the right permission on the executable, you might still be unable to use it via the kubectl command on the terminal, since the terminal uses PATH variables to locate the tool using aliases like kubectl. If an entry for the term kubectl isn't made in your system's PATH variable, the terminal won't be able to find the executable unless you specify its full path every time.
• Docker not running: If you use wsl on Windows and you've set up the kubectl tool as part of your Docker installation, you might receive this error if Docker isn't running on your system. This is because the tool is located inside of your Docker runtime, and your WSL command line forwards the kubectl command to a path like /mnt/wsl/docker-desktop/cli-tools/usr/local/bin/kubectl that is only available when Docker is running.
• Missing '-' when running kubectl inside minikube: If you're using minikube's instance of kubectl and you don't have a standalone installation of kubectl, you might need to verify that you're structuring your command properly. A -- is needed in the command to allow the options to be propagated to the kubectl tool instead of the minikube tool.

How to fix the kubectl command not found issue

If you've identified one of the above reasons as the cause of your kubectl command not found issue, you can use one of these solutions to fix it:

Kubectl is not installed locally

Ensure that you have installed kubectl locally. If you haven't, follow the installation instructions to set it up on your system. Make sure to add the required permissions and add it to your system's PATH.

If you're using kubectl via minikube, make sure you run the kubectl commands in the appropriate format (i.e., minikube kubectl -- options). In this case, you don't need to install kubectl independently on your system.

Typo in the command name

Ensure that you're typing the tool's name as kubectl. Make sure that all letters are lowercase and that you're not accidentally using any symbols in the name that may look similar to the name of the command.

Missing execution permissions on kubectl

If you're sure that you have the kubectl binary available on your system and that it's added to your PATH, verify that your terminal has the necessary permission to execute it. If not, use a tool like chmod to add the required permission. Here's how you can do this:

chmod +x /usr/local/bin/kubectl # replace this with the path to your kubectl binary

You can also go sudo to solve this problem. However, using sudo on a regular basis is not recommended. Instead, figure out the right permissions needed and add them to the binary file for smooth usage.

Missing the kubectl tool in your system's path

If you've identified that you have a local installation of the kubectl tool and you're able to access it by providing its full path (for instance, /path/to/kubectl.exe instead of just kubectl), you need to add it to your system's PATH variable to reference it as just kubectl from your command line. Depending on your operating system, you'll need to find the correct way to add it to your PATH. For *nix, here's how you can move the binary into the PATH location:

sudo mv ./kubectl /usr/local/bin/kubectl

Docker not running

If your kubectl CLI is based inside your Docker installation, start up Docker and see whether the command starts working again.

Missing '-' when running kubectl inside minikube

If you're using kubectl inside minikube, you need to add -- in your command to ensure that it's correctly formatted.

minikube kubectl -- get pods

The double dash (--) is used to signify the end of command options. Using a -- after minikube kubectl means that the options that you provide are meant to be passed on to kubectl and not minikube.

Final thoughts

Fixing kubectl command-not-found errors is mostly about local hygiene: install the binary, check PATH, verify permissions, and understand how Minikube wraps kubectl. It is not glamorous. It is necessary.

Polyaxon reduces how often ML users need kubectl, but platform engineers still need a working local Kubernetes toolchain. When the platform is down, the CLI is often what is left.