npx "<command>: not found" / "npm ERR! 404" - Fix Missing npx Binary in CI

npx runs a binary from node_modules/.bin or, failing that, fetches and runs it from the registry. In CI it fails when the tool was never installed, the binary name differs from the package, or the fetch 404s.

What this error means

An npx <tool> step fails with the tool "not found", or npx tries to fetch a package and gets a 404. It often happens when the package is a devDependency that a production install skipped, or the binary name is not the package name.

npx output

npm error could not determine executable to run
# or
npx: installed 1 in 2s
sh: 1: some-tool: not found
# or
npm error 404 Not Found - GET https://registry.npmjs.org/some-tool

Common causes

The tool was not installed for this job

A devDependency stripped by --omit=dev, or a tool never added to package.json, is not in node_modules/.bin, so npx falls back to a registry fetch that may 404.

The binary name differs from the package name

Some packages publish a binary whose name is not the package name. npx <package> works, but npx <binary> (or vice versa) can fail to resolve.

How to fix it

Install the tool and run its real binary

Add the package as a devDependency and invoke the correct binary name.

Terminal

npm install --save-dev some-tool
# run the binary npx finds in node_modules/.bin
npx some-tool --version
# if the binary name differs, name the package explicitly:
npx --package some-tool some-bin --version

Check installation and naming

Confirm the tool is in dependencies/devDependencies and installed in this job.
List node_modules/.bin to see the actual binary name.
For prod installs, do not rely on devDependency tools via npx.

How to prevent it

Add CLI tools as explicit devDependencies.
Invoke the binary name that ships in node_modules/.bin.
Avoid relying on npx to fetch tools at runtime in CI.