Esbuild Failed: Cannot find esbuild

WHAT IT MEANS

What this error means

SAM does not bundle esbuild. When a Node.js/TypeScript function opts into esbuild bundling via Metadata: BuildMethod: esbuild, SAM expects to find the esbuild binary through the function project's own dependencies. The failure shapes:

• esbuild is not declared in the function's package.json at all — it worked on a laptop only because of a global install.
• The CI job never ran npm ci (or yarn/pnpm install) before sam build, so node_modules is empty on the runner.
• The install ran in a different directory than the one containing the function's package.json — common in monorepos where CodeUri points at a subdirectory.
• Production-only installs — npm ci --omit=dev skips devDependencies, where esbuild normally lives.

FIX

How to fix it

1. Declare esbuild in the function project and commit the lockfile:

   cd path/to/function     # the directory with the function's package.json
   npm install --save-dev esbuild

2. Install before building in CI, in the same directory, without skipping dev dependencies:

   - name: Install function dependencies
     run: npm ci
     working-directory: path/to/function
   
   - name: Build
     run: sam build

3. In a monorepo, confirm which directory SAM builds. The function's CodeUri (or Metadata build properties) determine where SAM looks — the package.json containing esbuild must be there, not only at the repo root, unless your workspace tooling hoists it and SAM builds from the hoisted root.
4. Do not fall back to a global install as the fix. A global esbuild hides the missing declaration and breaks again on the next fresh runner. Pin a version in devDependencies so local and CI builds agree.
5. Re-run sam build. If it now fails on TypeScript resolution instead, that is a bundling configuration issue — check the EntryPoints in the function's build metadata.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the NodejsNpmEsbuildBuilder failure and the Esbuild Failed: Cannot find esbuild phrasing (high confidence), and keeps it distinct from generic SAM configuration errors. Runs locally; no AWS access, no log upload.

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED

Related errors

• Cannot connect to the Docker daemon — the container-build variant of a missing build tool.
• InsufficientCapabilitiesException — the next gate after the build starts passing.
• The REST API doesn't contain any methods — a template-shape failure that surfaces at deploy time.