Fixing npm Global Command Not Found on Windows

I recently hit a wall while configuring my development environment on Windows. It's one of those subtle issues that can waste an afternoon if you don't know what to look for. Here's exactly how I diagnosed and fixed a 'command not found' error after a successful global install.

The Problem
I decided to add a markdown processing tool to my toolkit by running:

npm install -g markdown-it-cli

The terminal output confirmed the installation succeeded, displaying a message about added packages. Satisfied, I tried to use it by typing markdown-it-cli in the command line. Windows immediately responded with: 'markdown-it-cli is not recognized as an internal or external command, operable program or batch file.'

This error means Windows looked through every folder in its search list and couldn't find an executable with that name.

Attempts and Failures
My initial reaction was to suspect the package itself might be broken. I tried running it using npx, which executes packages without requiring a global install:

npx markdown-it-cli -v

This worked instantly, printing the version number. Since npx could find and run the tool, I knew the package was functional. The failure was isolated to calling the command directly after a global install.

I needed to understand why npm couldn't find its own installation. I ran npm root -g, a command that shows the directory npm uses for global packages:

C:\Users\<user>\AppData\Roaming\npm

This told me exactly where npm had placed the executable files. Next, I checked my system's search paths using echo %PATH%. This command displays the list of directories Windows scans when looking for executables. The output showed entries for Windows system folders, Git, and Java, but the AppData\Roaming\npm directory was completely missing.

Root Cause
The root cause turned out to be the PATH environment variable all along.

On Windows, npm does not automatically add its global bin folder to your system PATH in every scenario. Depending on how Node.js was installed or updated, that critical path entry can get left behind. My echo %PATH% confirmed the directory where npm drops executables wasn't in the search list. Because the path was missing, Windows had no way to resolve markdown-it-cli when I typed it.

Final Solution
Fixing this required updating the environment variables, but there's a trap that caught me out. I opened Windows Environment Variables and added %AppData%\npm to the User PATH variable. This points directly to where npm root -g indicated my tools lived, ensuring Windows would find the executable.

I saved the change and immediately tried running markdown-it-cli in my current terminal window. It still failed with the same error.

The trap was that a running terminal holds the PATH snapshot from when it started. Updating environment variables doesn't retroactively fix an open session; the terminal process has already loaded its configuration. I had to close all terminal windows and open a brand new one for the OS changes to apply.

Once I opened a fresh terminal, running markdown-it -v worked perfectly. The command was recognized and executed as expected, confirming the fix.

Lesson Learned
When a global CLI installs successfully but won't run, don't rush to reinstall or blame the package. Before doing anything drastic, follow this diagnostic path:

1. Run npm root -g to find where npm installed the tool.
2. Check if that directory exists in your %PATH% using echo %PATH%.
3. If the path is missing, add it to your User PATH and open a new terminal.

Fixing the environment variable saves you from wasting time on package reinstalls and gets your global tools working again. Always verify the path before assuming a broken install.

Written from real hands-on experience, drafted with AI assistance.