NestJS app will not start: Cannot find module '/app/dist/main'
Error: 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
find prints nothing and the dist folder is missing or emptyThe project was never built before node ranFix - 2
find 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
The build works on your machine but the container reports Cannot find module '/app/dist/main'Docker did not get the dist folderFix - 4
The compiled main.js exists, but under a different folder than the one you runentryFile or sourceRoot points to a different layoutFix
- 1
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 dist2Fix
Run the build before the start command, in the same image or the same deploy step.
npm run build
node dist/main3Verify
dist/main.js exists and the app starts.
ls -l dist/main.jsConfirmed by docs.nestjs.com
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.jsConfirmed by typescriptlang.org
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" Dockerfile2Fix
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.jsConfirmed by docs.docker.com
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/main3Verify
The server prints its start-up log and listens.
curl -I http://127.0.0.1:3000Confirmed by docs.nestjs.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fixBack end
TypeError: something.default is not a constructor in a NestJS app
Exception has occurred: TypeError: xxx.default is not a constructor
TypeScript turns import X from 'pkg' into require('pkg').default when esModuleInterop is off, and a CommonJS package has no default, so new X() fails.
2 causes, each with a fixBack end
TypeScript cannot find req.cookies in a NestJS controller
error TS2339: Property 'cookies' does not exist on type
TypeScript says 'cookies' is missing because the Request type in your file is not Express's, or because cookie support is not installed.
3 causes, each with a fixBack end
TypeORM warns that createConnection is deprecated
'createConnection' is deprecated.
TypeORM replaced Connection with DataSource.
2 causes, each with a fixBack end
TypeORM stops with Duplicate migrations on run or generate
Error: Duplicate migrations: User1655123435373
TypeORM collects every migration class that your migrations glob matches and refuses to continue when two of them have the same class name.
2 causes, each with a fixBack end
TypeORM cannot find an entity, or the metadata for a relation
Entity metadata for Role#users was not found.
TypeORM only knows the entities listed in the entities option of the DataSource that is running.
2 causes, each with a fix