Kubectl command not found

kubectl is the standard command line tool used to interact with Kubernetes clusters. It can connect to all kinds of clusters and provide you with a uniform way of managing your Kubernetes deployments and services. This guide will show you how to solve the common kubectl command not found error message.

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:

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:

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:

Alternatively, you could create an alias for the command — you could set the value of kubectl to point to /path/to/kubectl.exe. This comes in handy when you don’t have permission to make changes to your system’s PATH variable (for example, on a corporate system).

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.

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

The kubectl command not found error can be tricky to solve, as it can occur for many reasons. In this guide, we presented a roundup of these reasons and solutions that can help you fix the issue quickly.

If you're looking to build workflows that can help you catch errors like this, Airplane is a great solution for you. Airplane is the developer platform for building custom internal tools. With Airplane, engineers can transform scripts, queries, APIs, and more into powerful internal UIs and workflows.

Airplane is also a great fit for your engineering-centric use cases. You can build incident command centers and AWS ECS dashboards, schedule recurring jobs, execute on-call runbooks, and more.

To build an engineering workflow that can help catch Kubernetes cluster errors, sign up for a free account or book a demo.