Node "Error: Cannot find module 'X'" in CI - Fix Module Resolution

By Daniel Zoghalchali·Latchkey

Cannot find module means Node started running your code but require() resolved a path that does not exist on disk in CI, even if it works locally.

What this error means

A node script starts, then throws Error: Cannot find module with a require stack pointing at one of your own files or a dependency. It often passes locally but fails on a clean CI checkout.

Error: Cannot find module './utils/format'
Require stack:
- /home/runner/work/app/app/src/index.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1145:15)
    at Module._load (node:internal/modules/cjs/loader:986:27)

Common causes

A path that only resolves because of local case-insensitivity

macOS and Windows filesystems are case-insensitive, so ./Utils/Format resolves locally but fails on the case-sensitive Linux CI runner.

The compiled output was never built

The script requires a file under dist/ or build/ that the CI job never produced because the build step was skipped or failed silently.

How to fix it

Match the path exactly, including case

1. Compare the required path against the real filename letter by letter.
2. Fix any case mismatch so it resolves on a case-sensitive Linux filesystem.
3. Commit the corrected import and re-run the job.

Ensure the build runs before the script

1. Confirm the dist/ or build/ directory the script needs is produced earlier in the job.
2. Add the build step before the failing run step.

- run: npm run build
- run: node dist/index.js

How to prevent it

• Use case-sensitive paths everywhere, keep build output out of git, and order CI steps so every required artifact is produced before the script that consumes it.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation