Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

vite build cannot find index.html, especially inside Docker

ErrorCould 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.

  • Applies to Vite 6, Vite 7, Node.js 22, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -la
  2. 2Match what you see, then jump to its fix

    1. 1ls 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. 2The 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. 3COPY . . is present, yet index.html is missing inside the image.dockerignore removes index.html from the build contextFix
    4. 4You 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

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" Dockerfile

2Fix

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 build

3Verify

Build the image again and confirm the Vite output lists the generated files.

docker build -t my-web .

Confirmed by vite.dev

Did this fix it?

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" Dockerfile

2Fix

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 build

3Verify

Rebuild the image without cache and check that the build step passes.

docker build --no-cache -t my-web .

Confirmed by docs.docker.com

Did this fix it?

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 .dockerignore

2Fix

Remove the rule that matches index.html. Keep node_modules and dist excluded.

# .dockerignore
node_modules
dist
.git

3Verify

Rebuild the image and run the listing again.

docker build --no-cache -t my-web .

Confirmed by docs.docker.com

Did this fix it?

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.json

2Fix

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 build

3Verify

Run the build from the root again.

npx vite build

Confirmed by vite.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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