vite build cannot find index.html, especially inside Docker
Could not resolve entry module (index.html)Short answer
Vite treats index.html as the entry of the app and looks for it in the project root, which is the folder where you run the command. The error means that folder has no index.html. In Docker, check WORKDIR and the COPY lines first, then .dockerignore, then any custom root setting.
Fix it fast
1Find out which cause you have
List the files in the folder where vite build runs. In a container, run the same listing inside the build, with the image you are building.
pwd && ls -la # in a Dockerfile, temporarily add: RUN pwd && ls -la2Match what you see, then jump to its fix
- 1
ls shows no index.html, but the file exists one folder up or downThe command runs in a folder that is not the project rootFix - 2
The Dockerfile copies only package files or src, and the listing inside the image shows no index.htmlCOPY did not bring index.html into the imageFix - 3
COPY . . is present, yet index.html is missing inside the image.dockerignore removes index.html from the build contextFix - 4
You changed the Vite root, or run vite for a sub folder, and the build now failsA different root was set and index.html or the config did not move with itFix
- 1
What does the error look like?
Could not resolve entry module (index.html)
Cause 1 of 4
The command runs in a folder that is not the project root
1Check
Vite uses the current working directory as root unless you pass another one. In a Dockerfile, a relative WORKDIR is resolved against the previous WORKDIR, so a repeated or nested WORKDIR line changes the folder silently.
grep -n "WORKDIR\|COPY\|RUN npm" Dockerfile2Fix
Run the build from the folder that holds index.html and package.json, or pass that folder to Vite.
WORKDIR /app
COPY . .
RUN npm ci && npx vite build3Verify
Build the image again and confirm the Vite output lists the generated files.
docker build -t my-web .Confirmed by vite.dev
Cause 2 of 4
COPY did not bring index.html into the image
1Check
COPY reads sources relative to the root of the build context. If the Dockerfile copies only a subfolder, index.html at the project root never reaches the image.
grep -n "COPY" Dockerfile2Fix
Copy the whole project, or add a COPY line for index.html and the other root files, before the build step.
COPY package*.json ./
RUN npm ci
COPY index.html vite.config.* ./
COPY src ./src
COPY public ./public
RUN npx vite build3Verify
Rebuild the image without cache and check that the build step passes.
docker build --no-cache -t my-web .Confirmed by docs.docker.com
Cause 3 of 4
.dockerignore removes index.html from the build context
1Check
A .dockerignore file excludes files and directories from the build context, and COPY can only copy what is in the context. A pattern such as *.html or a broad rule can hide the entry file.
cat .dockerignore2Fix
Remove the rule that matches index.html. Keep node_modules and dist excluded.
# .dockerignore
node_modules
dist
.git3Verify
Rebuild the image and run the listing again.
docker build --no-cache -t my-web .Confirmed by docs.docker.com
Cause 4 of 4
A different root was set and index.html or the config did not move with it
1Check
Vite can serve a sub folder as root. It resolves its config file inside the project root, so a config that stayed behind is not read, and the sub folder needs its own index.html.
grep -rn "root" vite.config.* package.json2Fix
Put index.html in the folder you set as root, and move the config file with it.
# project/
# vite.config.js
# index.html
npx vite build3Verify
Run the build from the root again.
npx vite buildConfirmed by vite.dev
How do I stop it coming back?
- Pin one WORKDIR in the Dockerfile and avoid repeating it with relative paths.
- Review .dockerignore whenever a new root-level file becomes part of the build.
- Run the same build command locally and in the Dockerfile so they see the same folder.
- Keep index.html at the top level of the project, as Vite expects.
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.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
Playwright cannot open a headed browser on a Linux server or in Docker
npx playwright test --headed shows no window on a Linux server
A headed browser needs a display, and a Linux server or container has none.
3 causes, each with a fixWeb apps
React dev server in Docker does not reload when you save a file
Changes appear only after docker compose restart or a rebuild
File-change events often do not cross from your host into a container, so the dev server never notices the edit.
3 causes, each with a fixWeb apps
npm install fails with 'sh: node-gyp-build: command not found'
npm error command failed
A package's install script calls node-gyp-build by name.
2 causes, each with a fixWeb apps
T3 Env stops the build with Invalid environment variables
Error: Invalid environment variables
T3 Env validates process.env against your Zod schema when the app starts or builds, and stops on the first failure.
4 causes, each with a fixWeb apps
Vite environment variables are undefined inside a Docker container
VITE_ variable shows undefined in the browser console
Vite replaces import.meta.env values while it builds, not when the container starts.
3 causes, each with a fixWeb apps
Vite cannot find the sass preprocessor you import
The same message during vite build in CI or Docker, although it works on your machine
Vite compiles .scss and .sass files but does not ship the compiler.
2 causes, each with a fix