Frustrated when a command works for your user but mysteriously fails with ‘sudo: command not found’? We break down why your environment changes when you elevate privileges and provide three concrete solutions to fix it for good.

“Sudo: Command Not Found” — A DevOps War Story

I remember it like it was yesterday. It was 2 AM, the go-live was in a few hours, and one of our sharpest junior engineers, let’s call him Leo, was on the verge of throwing his laptop out the window. His deployment script, which used a Node.js process manager called ‘pm2’, worked flawlessly on his local machine and even when he ran it as his user on the staging server, `stage-app-01`. But the second our Jenkins pipeline tried to run it with sudo -u deploy-user pm2 restart all, it blew up. The error? A soul-crushing sudo: pm2: command not found.

Leo was adamant. “But it’s right there! I installed it globally! I’m Gen Z, Darian, I know how to use a computer!” He wasn’t wrong. He was smart, and he did know how to use a computer. What he hadn’t yet learned in the trenches is that a server doesn’t care how smart you are; it only cares about its environment. And sudo has its own ideas about that.

The “Why”: You’re Not in Kansas Anymore

Here’s the critical piece of the puzzle that trips everyone up at some point: when you run a command with sudo, you are not just running your command as the root user. For security reasons, sudo sanitizes the environment. It loads a fresh, minimal one to prevent potentially malicious environment variables from your user session from being used in a privileged context. The most important variable it changes is $PATH.

Your personal user account has a $PATH that includes all sorts of convenient locations, like /home/leo/.nvm/versions/node/v20.5.1/bin or /home/leo/.local/bin. The default, secure $PATH used by sudo is much stricter, typically something like /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin.

If your tool (like pm2, npm, ansible-playbook, etc.) isn’t in one of those standard directories, sudo won’t find it. It’s not a bug; it’s a security feature.

Three Ways to Tame the Sudo Beast

So, how do we fix it? Here are three approaches, ranging from a quick battlefield patch to a proper architectural solution.

Solution 1: The Full-Path Hammer (The Quick Fix)

This is the simplest, most direct way to solve the problem, and it’s great for debugging or a one-off command. You just tell the shell exactly where the executable is. First, find the full path using the which command as your normal user:

which pm2

Let’s say it returns /home/leo/.nvm/versions/node/v20.5.1/bin/pm2. Now, you just use that full path in your sudo command:

sudo /home/leo/.nvm/versions/node/v20.5.1/bin/pm2 restart all

It’s ugly and brittle (what happens when you update Node?), but it gets you out of a jam. Think of it as a temporary patch, not a permanent fix.

Solution 2: The Symlink Bridge (The ‘Proper’ Fix)

This is my preferred method. It’s clean, permanent, and respects the system’s security model. We create a symbolic link (a “symlink”) from our tool’s actual location to a directory that is in the secure PATH, like /usr/local/bin.

This tells the system, “Hey, whenever someone in a secure context looks for ‘pm2’, the real file is over here.”

sudo ln -s /home/leo/.nvm/versions/node/v20.5.1/bin/pm2 /usr/local/bin/pm2

Now, your original command will work perfectly, because /usr/local/bin is a standard, trusted location.

sudo pm2 restart all
# It just works!

Pro Tip: This is the most idempotent and script-friendly solution. When you provision a new server, your setup script can create this symlink, ensuring the environment is always correct without having to modify sensitive system-wide configuration files.

Solution 3: The Sudoers Edit (The ‘Nuclear’ Option)

I hesitate to even mention this one, but for completeness, you need to know it exists. You can directly edit the sudoers configuration file to modify the secure path. Tread very, very carefully here. A syntax error in this file can lock you out of your own server, including your ability to use sudo to fix it.

ALWAYS edit this file using the visudo command, which will perform a syntax check before saving.

sudo visudo

Inside the file, you will find a line that looks something like this:

Defaults    secure_path = /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

You can append the path to your tool’s directory to this line. For example:

Defaults    secure_path = /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/leo/.nvm/versions/node/v20.5.1/bin

This is a powerful but blunt instrument. It affects every single sudo command on the system and can have unintended security consequences. I only recommend this in highly controlled environments where you have a very specific, unchanging need.

Which Fix Should You Use? A Quick Comparison

Method	Pros	Cons	Best For…
1. Full Path	Simple, immediate, no system changes.	Brittle, not scalable, ugly.	Quick debugging or one-off tasks.
2. Symlink	Clean, robust, follows best practices.	Requires an extra setup step.	Almost all production scenarios.
3. Sudoers Edit	Fixes the issue for all tools in that path.	DANGEROUS. System-wide change, high risk.	Highly specialized, controlled environments.

In the end, Leo and I created a symlink. The pipeline turned green, the deployment went live, and we all got a few hours of sleep. The lesson wasn’t about knowing how to use a computer; it was about understanding that the computer’s context can be wildly different from your own. And that, my friends, is a lesson every one of us in this field learns the hard way.

---

🤖 Frequently Asked Questions