Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

NestJS app will not start: Cannot find module '/app/dist/main'

ErrorError: Cannot find module '/app/dist/main'

Short answer

Node cannot find dist/main.js because the build did not put it there. Run nest build and list dist. If main.js sits in dist/src, a file outside src widened the TypeScript root folder. In Docker, the dist folder may be excluded by .dockerignore or never copied into the final stage.

  • Applies to NestJS 11, TypeScript 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Build the project and look at what was produced. The place of main.js tells you which cause below applies.

    npx nest build
    find dist -maxdepth 2 -name "main.js"
  2. 2Match what you see, then jump to its fix

    1. 1find prints nothing and the dist folder is missing or emptyThe project was never built before node ranFix
    2. 2find prints dist/src/main.js instead of dist/main.jsA file outside src widened the TypeScript root, so the output is dist/src/main.jsFix
    3. 3The build works on your machine but the container reports Cannot find module '/app/dist/main'Docker did not get the dist folderFix
    4. 4The compiled main.js exists, but under a different folder than the one you runentryFile or sourceRoot points to a different layoutFix

What does the error look like?

  • Error: Cannot find module '/app/dist/main'
  • Cannot find module 'dist/main'

Cause 1 of 4

The project was never built before node ran

1Check

Check the start script that runs in production. node dist/main only runs compiled output, so something must run the build first.

grep -n '"build"\|"start' package.json
ls dist

2Fix

Run the build before the start command, in the same image or the same deploy step.

npm run build
node dist/main

3Verify

dist/main.js exists and the app starts.

ls -l dist/main.js

Confirmed by docs.nestjs.com

Did this fix it?

Cause 2 of 4

A file outside src widened the TypeScript root, so the output is dist/src/main.js

1Check

TypeScript keeps the folder layout relative to the common root of all input files. When tsconfig includes a file outside src (a seed script, a config in the project root, a test folder), the root becomes the project folder and src is kept in the output path.

cat tsconfig.build.json
find dist -maxdepth 2 -name "main.js"

2Fix

Limit the build to the src folder in tsconfig.build.json, then delete dist and build again. Setting rootDir to src also works, but then TypeScript reports an error for any file outside it, which shows you the file that caused the problem.

// tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "include": ["src/**/*"],
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}

3Verify

After a clean build the file is at dist/main.js.

rm -rf dist
npx nest build
ls dist/main.js

Confirmed by typescriptlang.org

Did this fix it?

Cause 3 of 4

Docker did not get the dist folder

1Check

A line in .dockerignore removes files from the build context, so COPY cannot see them. In a multi-stage Dockerfile, the final stage only contains what you copy into it with COPY --from.

cat .dockerignore
grep -n "FROM\|COPY\|CMD" Dockerfile

2Fix

Build inside the image, and copy dist from the build stage into the final stage. Do not rely on a dist folder from your own machine.

FROM node:22-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/main"]

3Verify

List the files inside the built image.

docker build -t my-api .
docker run --rm my-api ls dist/main.js

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

entryFile or sourceRoot points to a different layout

1Check

nest start runs the entry file set by entryFile and sourceRoot in nest-cli.json (the CLI flags --entryFile and --sourceRoot override them). If these differ from the layout of your build output, the path you run by hand will not match.

cat nest-cli.json
find dist -name "main.js" -not -path "*/node_modules/*"

2Fix

Run the exact path you found, or make the start script call nest start with the same settings you use in development.

node dist/apps/api/main

3Verify

The server prints its start-up log and listens.

curl -I http://127.0.0.1:3000

Confirmed by docs.nestjs.com

Did this fix it?

How do I stop it coming back?

  • Keep one start script for production and make the Dockerfile call it, so the command is the same everywhere.
  • Keep non-source files (seed scripts, tooling configs) out of tsconfig.build.json.
  • Copy only dist, package files and production dependencies into the final image.
  • Run a smoke test in CI that starts the built image and requests one route.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.