esbuild "Could not resolve" import in CI

By Kaveh Alemi·Latchkey

esbuild walked the import graph and could not locate the named module. The path does not point to a real file, the package is not installed, or the import case does not match the file on a case-sensitive runner.

What this error means

The build fails with "[ERROR] Could not resolve 'X'" and a code frame pointing at the import line.

> src/index.ts:1:18: ERROR: Could not resolve "./utils/format"
    1 | import { fmt } from "./utils/format";
      |                      ~~~~~~~~~~~~~~~~~
1 error

Common causes

A missing dependency or wrong relative path

The package was never installed in CI, or the relative path does not point to an existing file.

Case mismatch on a case-sensitive filesystem

Linux runners distinguish case, so ./Format will not resolve a file named format.ts.

How to fix it

Correct the path or install the dependency

1. Confirm the imported file or package exists with the exact name and case.
2. Install missing packages or fix the relative path.
3. Re-run the build to confirm esbuild resolves it.

npm ci
npx esbuild src/index.ts --bundle --outfile=out.js

Add resolve extensions or node paths if needed

If imports omit extensions or rely on extra roots, configure esbuild so it can find them.

npx esbuild src/index.ts --bundle \
  --resolve-extensions=.ts,.js,.json

How to prevent it

• Match import paths to real file names and case.
• Commit a lockfile so CI installs every imported package.
• Keep resolve extensions configured for your file types.

Frequently asked questions

Related guides

References

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