Bun "Cannot find module" in CI

Bun could not resolve an import. Either dependencies were never installed, a relative path is wrong, or a path alias is not configured - so the module is not where Bun looks.

What this error means

A bun run or test aborts with "error: Cannot find module \"<name>\"". For a package name it usually means bun install did not run; for a relative path it means the path or extension is wrong.

bun output

error: Cannot find module "@app/utils" from "/app/src/main.ts"
# or
error: Cannot find module "./helpers" from "/app/src/index.ts"

Common causes

Dependencies not installed

If bun install did not run (or node_modules was not restored), package imports cannot resolve. This is the most common CI cause.

Wrong relative path or unconfigured alias

A relative import with a wrong path, or a path alias like @app/* not declared in tsconfig.json paths, leaves the specifier unresolved.

How to fix it

Install dependencies first

Run bun install before running or testing so packages exist.

Terminal

bun install --frozen-lockfile
bun run start

Fix the path or declare the alias

Correct the relative path, or define the alias in tsconfig so Bun resolves it.

tsconfig.json

{
  "compilerOptions": {
    "paths": { "@app/*": ["./src/*"] }
  }
}

How to prevent it

Run bun install (ideally --frozen-lockfile) before any run/test step.
Cache Bun’s install cache keyed on bun.lockb.
Declare path aliases in tsconfig.json so they resolve consistently.