---
title: "Troubleshooting mabl CLI installation"
description: "If you encounter issues when installing the mabl CLI, use this guide to troubleshoot common problems that prevent mabl CLI commands from working:..."
last_updated: "2026-02-27"
source_url: "https://help.mabl.com/hc/en-us/articles/38331058960276-Troubleshooting-mabl-CLI-installation"
---

# Troubleshooting mabl CLI installation

> For the full index of agent-friendly pages, see [llms.txt](/llms.txt).

If you encounter issues when [installing the mabl CLI](./installing-and-configuring-the-mabl-cli.md), use this guide to troubleshoot common problems that prevent mabl CLI commands from working:

- [Permissions errors](#h_01JXFRE3ZPDEWMD6X5DWMQHTTM)
- [“Command not found” errors](#h_01JXFRE3ZQG8F0YRQXY6B62E3K)
- [Unsupported Node.js version](#h_01JXFRE3ZQKRWYVSBVQAK1FCNZ)
- [Proxy issues](#h_01JXFRE3ZQDFH8AGF88EDNCWFN)

## Permissions errors

If you see an “Access denied” message when installing the mabl CLI, such as `EACCES: permission denied`, you are likely encountering a permissions error. Permissions errors indicate that you lack permissions to install the mabl CLI Node package globally.

To resolve this issue, update npm so that it installs global packages in a directory that you own and have full access to. Here are a few ways you can do this:

- Use a Node Version Manager, such as [nvm](https://github.com/nvm-sh/nvm) or [nvm-windows](https://github.com/coreybutler/nvm-windows). NVMs automatically manage global package installations in user-owned directories.
- Manually update npm’s global package directory by adjusting npm’s configuration with commands like `npm config set` or by directly editing the `.npmrc`. file

Updating npm prevents the need for `sudo` commands and avoids the most common permissions errors. After updating npm, try [installing the mabl CLI](./installing-and-configuring-the-mabl-cli.md) again.

## “Command not found” errors

If you see “Command not found”-type errors when you run `mabl` commands in the terminal or command prompt, your operating system (OS) cannot locate what you are trying to run.

When you run commands in the terminal, your OS searches for directories listed in your system’s `PATH` environment variable. For example, if you run `mabl --version`, your OS looks in the `PATH` variable for the directory where the mabl CLI is installed. If that directory isn’t installed or isn’t included in the `PATH` variable, your system doesn’t know where to find it and returns a message like `mabl: Command not found`.

To resolve this issue, you can manually add the npm global packages directory to your system’s `PATH`:

### Mac and Linux users

1.  In the terminal, run `npm root -g` to find the directory for npm global packages.
2.  Run `echo $PATH` and check if the directory from step 1 is included in the list.
3.  If the directory isn’t listed, add it to the `PATH` variable. The `PATH` variable is often located in your shell’s configuration file (e.g. `.zshrc`, `.bashrc`, or `.profile`) in the home directory (`~`). Open the configuration file in a text editor and add a line like this, replacing `/path/to/your/npm/global/packages` with the output from step 1:

 

    export PATH="/path/to/your/npm/global/packages:$PATH

4.  After saving the configuration file, restart your terminal to apply the changes.
5.  To confirm that your OS can find `mabl` CLI commands, run `mabl -v` in the terminal.

### Windows users

1.  In the command prompt, run `npm root -g` to get the directory for npm global packages.
2.  Search for “Environment Variables’”in the Windows search bar, then click on **Edit the system environment variables.**
3.  In System Properties, click on **Environment Variables**
4.  Select the `PATH` variable for the logged-in user and click on **Edit**
5.  Add the directory from step 1 to the `PATH` variable
6.  Save your changes
7.  To confirm that your OS can find `mabl` CLI commands, run `mabl -v` in the command prompt.

> **Note:**
> **If "Command not found" errors persist**
>
> If you still get "Command not found" errors after updating the `PATH`, the mabl CLI might not be installed correctly or at all. In this situation, the best next step is to try [installing the mabl CLI again](./installing-and-configuring-the-mabl-cli.md).

## Unsupported Node.js version

If you see messages indicating Node.js version requirements when installing the mabl CLI, such as `npm WARN notsup Unsupported engine`, the Node version that is currently active in your command line does not meet the minimum requirements for the mabl CLI.

If this happens, try the following troubleshooting steps:

1.  Run `node -v` to check which version of Node is active in your command line. The mabl CLI requires an actively supported Long Term Support (LTS) version of Node.
2.  If your version is out of date, download and install a supported version from the [Node.js](http://Node.js) website.
3.  If there are multiple versions of Node on your machine, consider using a Node Version Manager (NVM), such as [nvm](https://github.com/nvm-sh/nvm) or [nvm-windows](https://github.com/coreybutler/nvm-windows), to simplify management. Alternatively, you can manually adjust your system’s `PATH` to ensure the desired Node version comes before older versions.

After installing/updating Node, try [installing the mabl CLI](./installing-and-configuring-the-mabl-cli.md) again.

## Proxy issues

If you see errors like this when you install the mabl CLI, you may need to configure proxy settings for `npm`:

- `ETIMEDOUT` - connection timeout
- `ECONNREFUSED` - connection refused
- `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` - SSL certificate issues, often related to proxies
- `SELF_SIGNED_CERT_IN_CHAIN` - another common SSL proxy error

If you aren’t sure whether your organization uses a corporate firewall or proxy server to control Internet access, check with your IT department or network administrator. They can provide the correct proxy address and port.

### Configure proxy settings for npm

Use the following commands to set proxies for `npm`. Replace `http://proxy.example.com:8080` with your actual proxy address and port.:

    # Set HTTP proxy  
    npm config set proxy http://proxy.example.com:8080
    # Set HTTPS proxy  
    npm config set https-proxy http://proxy.example.com:8080  

After configuring `npm` with your proxy settings, try [installing the mabl CLI](./installing-and-configuring-the-mabl-cli.md) again.