Vitest "vitest: command not found" in CI

By Daniel Zoghalchali·Latchkey

The shell could not find a vitest executable. In CI this almost always means node_modules/.bin was never populated: dependencies were not installed, only production deps were installed, or the step ran from the wrong directory.

What this error means

A test step invoking vitest or npm test fails immediately with "vitest: command not found" and exit code 127, before any test file loads.

sh: 1: vitest: command not found
npm ERR! Lifecycle script `test` failed with error:
npm ERR! code 127

Common causes

Dependencies were not installed

The job ran the test step without a prior npm ci, or restored a cache that did not include node_modules/.bin/vitest, so no binary exists.

Only production dependencies were installed

Vitest is a devDependency. Installing with --omit=dev or NODE_ENV=production skips it, so the binary is absent in CI.

How to fix it

Install dev dependencies before testing

1. Run npm ci (which installs dev deps by default) before the test step.
2. Ensure you did not set NODE_ENV=production or pass --omit=dev.
3. Invoke vitest through an npm script so node_modules/.bin is on PATH.

- run: npm ci
- run: npm test   # "test": "vitest run" in package.json

Call the binary via npx or the package script

If you must invoke it directly, use npx vitest run so the local binary resolves even outside an npm lifecycle script.

npx vitest run

How to prevent it

• Always run npm ci (not npm ci --omit=dev) before the test job.
• Keep vitest in devDependencies and call it through package scripts.
• Do not set NODE_ENV=production in a job that runs tests.

Frequently asked questions

Related guides

References

• GitHub Actions documentation