Troubleshooting ‘ZSH Command Not Found’ Errors for MongoDB

You are probably aware that you when running a command in a Unix shell, the target binary must be in the system path environment variable. This is because the system evaluates the directories in this variable to determine where to look for the binary.

However, when working with ZSH, you might encounter a scenario where you get the “command not found” error. In this tutorial, we will walk you to the process of troubleshooting and resolving the “command not found” error in a MongoDB context using ZSH.

In this post, we assume that you have a fundamental knowledge on shell environments, MongoDB, and other system-level Unix-features.

Prerequisites:

Before we dive into the troubleshooting phase, ensure that you have the following:

1. Installed MongoDB on your machine
2. Access to a terminal that is running the ZSH shell
3. Necessary permissions to execute or alter the MongoDB binaries

The Basics

Now, before we dive into the troubleshooting phase, let us explore some fundamental features and concepts that allow you to get a fundamental cause of this issue. This helps you to troubleshoot other related problems.

1. ZSH – ZSH is a Unix shell that allows for interactive login and works as a powerful command interpreter for shell scripting. It is similar to other Unix shell interpreters such as Bash, CSH, and more.
2. Binary – The second thing that we need to understand is the binary. This is basically the executable that we wish the system to run when we run a command. In our example, this is the MongoDB shell which we can invoke using mongosh. Binaries in a Unix system are stored in strategic directories. The system knows where these directories are by looking at the path environment variable.
3. PATH Environment Variable – This is a system variable that tells the shell where to look for executable files.
4. Shell Configuration files – Lastly, we have the configuration files for each of the target shell. For example, in a shell such as Bash, you have a file like “.bashrc” in your home directory. The role of this file is to determine the workings of your shell including where to look for various commands, functions, aliases, and more. For ZSH, this is determined by the “.zshrc” and the “.zprofile” files.

Method 1: Check If MongoDB Is Installed

The first step is to always ensure that you installed the binary that you wish to run on your system.

For MongoDB, you can run the “mongod” command as follows:

If you have MongoDB installed on your machine, you should get a detailed information about the installed server version as follows:

However, if you get the “zsh: command not found: mongod” error, it means that you do not have the MongoDB installed. Install it first.

Method 2: Verify the $PATH Variable

If you confirm that you have MongoDB installed on your machine but you are still getting the “ZSH: Command not found: Mongod” error, proceed to the next step where we troubleshoot the “$path” variable in your system.

To verify that the PATH variable includes the directory where the MongoDB binaries are located, run the following command:

From the resulting output, examine it to see if you can find the path to the MongoDB binaries. For example, if the “mongod” binary is stored in “/usr/local/bin”, ensure that this directory is available in the path.

Adding a Directory to the PATH

If the directory that contains the MongoDB binaries is not available in the system path, you need to add it to resolve this error.

You can start by checking where MongoDB is installed by running the following command:

This should return the path to where the “mongod” path is located. Note down this path as we will need it in the next step.

Once we locate the correct path, add it to the PATH variable by running the following command:

Be sure to replace the “/path/to/mongodb” with the actual path that you copied from the “find” command in the previous step.

To make the changes permanent, you can add the value to your ZSH configuration file as shown in the following command:

Finally, apply the changes to your current shell session using the source command as follows:

Method 3: Shell Aliases and Functions

The third technique that you can use is examining your shell aliases and functions. You may have a function or alias that is overriding the command that you wish to run.

This command should tell you whether there are any aliases or functions that override the “mongod” command. If there are any, remove them from your shell configuration files.

Method 4: File Permissions

You can also encounter this error if you do not have the correct permissions on your MongoDB binaries. This can occur if you manually install MongoDB by copying the downloaded archive without setting the target permissions.

To resolve this, you can set the “execute” permissions on all the MongoDB binaries as shown in the following:

Ensure that the MongoDB binaries have the correct permissions to be executed.

In this case, we add the “execute” permission to the “mongod” binary.

Method 5: Advanced Debugging Using ZSH Startup Files

If none of the previous techniques works, you can take the troubleshooting step further by enabling the “debug” mode for ZSH and printing all the startup messages.

This can help you determine where the error might be occurring.

To enable the “debug” mode in ZSH, use the following command:

This should provide a high verbosity level which should enable you to view the operations that occur in the ZSH shell.

Conclusion

In this tutorial, we walked you through the steps of troubleshooting the “command not found” error when running the MongoDB commands in the ZSH shell.