Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

The nginx container serves the default page or 404 because /usr/share/nginx/html has no app files

Errorthe browser shows the default nginx start page instead of your app

Short answer

The official nginx image serves whatever sits in /usr/share/nginx/html. If your site is missing, the files never got copied there: the COPY path is wrong, the build output folder has another name than the one you copied, or a bind mount hides what the image holds. List the folder inside the running container first.

  • Applies to Docker Engine 28, nginx official image, Vite, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look inside the running container at the folder nginx serves. If you see none of your files, your build output never arrived.

    docker ps
    docker exec my-web ls -la /usr/share/nginx/html
  2. 2Match what you see, then jump to its fix

    1. 1The multi-stage build succeeds, but the final image holds only the files the image shipped with, or COPY --from fails with a not found errorThe build output folder is not the folder you copiedFix
    2. 2Single-stage Dockerfile with COPY dist /usr/share/nginx/html, and the build errors with not found or copies nothing usefulThe files are not in the build context, or the path is wrongFix
    3. 3docker exec shows an empty or different folder than the one baked into the imageA bind mount covers the files that the image containsFix

What does the error look like?

  • the browser shows the default nginx start page instead of your app
  • requests for your pages return 404 Not Found
  • COPY --from fails because the source path was not found in the build stage

Cause 1 of 3

The build output folder is not the folder you copied

1Check

COPY --from reads its source path from the root of the build stage, so the path must be the real output location. Vite writes to dist by default; other tools use build, out or a nested folder. Check what the build stage really produced.

# Dockerfile, in the build stage
# add this line after the build step of the build stage, then rebuild
RUN ls -la /app

2Fix

Copy the folder the build produced into the web root of the last stage. Only the last stage becomes the image.

FROM node:22 AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build

FROM nginx:stable
COPY --from=build /app/dist /usr/share/nginx/html

3Verify

Rebuild and list the web root in the new container.

docker build -t my-web .
docker run --rm my-web ls -la /usr/share/nginx/html

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The files are not in the build context, or the path is wrong

1Check

A plain COPY reads paths relative to the root of the build context, the folder you pass to docker build. Files outside it, or files excluded by .dockerignore, are not there. A dist folder that you never built on the host cannot be copied.

ls -la dist
cat .dockerignore

2Fix

Build the app first on the host, or use a multi-stage build so Docker builds it for you. Remove the folder from .dockerignore if you copy a pre-built one.

npm run build
docker build -t my-web .

3Verify

The image lists your files in the web root.

docker run --rm my-web ls -la /usr/share/nginx/html

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

A bind mount covers the files that the image contains

1Check

Mounting a host folder over /usr/share/nginx/html hides what the image had there. If the host folder does not exist, docker run -v creates it empty, and nginx has nothing to serve.

docker inspect my-web

2Fix

Either mount the folder that really holds your built site, read-only, or remove the mount and use the files baked into the image. The nginx image's own docs call copying files in a Dockerfile the cleaner way.

docker run --name my-web -v /srv/site/dist:/usr/share/nginx/html:ro -d -p 8080:80 nginx

3Verify

Request the site from the host.

curl -I http://localhost:8080/

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Print the output folder in CI (ls after the build step) so a renamed output directory is noticed at once.
  • Use a multi-stage Dockerfile so the image does not depend on a folder that exists only on one laptop.
  • Keep dist (or your output folder) out of .dockerignore only when you copy a pre-built folder.

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.