Maaz Zindani

Loading the index…

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

The Next.js container starts with docker run but Compose fails with next: not found

Errorsh: next: not found

Short answer

The shell cannot find the next binary. Under Compose that is usually a bind mount such as .:/app hiding the node_modules folder built into the image. Other causes are a CMD that calls next directly instead of through npm, and a standalone image, which contains no next binary and starts with node server.js.

  • Applies to Docker Engine 27, Docker Compose 2, Node.js 22, Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look inside the running service to see whether node_modules exists where the app expects it. An empty or missing folder points at the volume cause first.

    docker compose run --rm --entrypoint sh web -c "ls /app/node_modules/.bin | head; pwd"
  2. 2Match what you see, then jump to its fix

    1. 1docker run works, Compose fails; the compose file has a volume like .:/appA bind mount hides the node_modules installed in the imageFix
    2. 2The error appears with exec form CMD ["next", "start"] or a Compose command: next startThe command calls next directly instead of through npmFix
    3. 3The runtime stage copies .next/standalone, and the start command is still next startThe image uses output: standalone, which has no next binaryFix

What does the error look like?

  • sh: next: not found
  • /bin/sh: 1: next: not found

Cause 1 of 3

A bind mount hides the node_modules installed in the image

1Check

Mounting a host folder onto a folder that already has content in the image hides that content for as long as the mount exists. If node_modules is not installed on the host, /app/node_modules is empty inside the container.

grep -n -A4 "volumes:" compose.yaml
ls node_modules/.bin/next

2Fix

Mount only the folders you edit, so the image's node_modules stays visible, or run npm install on the host as well.

services:
  web:
    build: .
    volumes:
      - ./app:/app/app
      - ./public:/app/public

3Verify

Recreate the service and list the binary inside it.

docker compose up -d --force-recreate
docker compose exec web ls node_modules/.bin/next

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The command calls next directly instead of through npm

1Check

npm run adds node_modules/.bin to PATH for the script. A command started without npm gets only the container's normal PATH, which does not include that folder.

grep -n "CMD\|command:" Dockerfile compose.yaml

2Fix

Run the script from package.json, or call the binary by its path.

CMD ["npm", "run", "start"]
# or
CMD ["./node_modules/.bin/next", "start"]

3Verify

Rebuild and read the container logs.

docker compose up -d --build
docker compose logs web --tail 20

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The image uses output: standalone, which has no next binary

1Check

The standalone folder is a self-contained server that is deployed without installing node_modules. It ships a minimal server.js that is used instead of next start.

grep -n "standalone" next.config.js next.config.mjs Dockerfile

2Fix

Start the server with node, and copy the static folders next to it, because standalone does not include public or .next/static.

COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
CMD ["node", "server.js"]

3Verify

Rebuild, start the service and request a page and a static file.

docker compose up -d --build
curl -I http://127.0.0.1:3000/

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • In development Compose files, mount source folders one by one instead of the whole project root.
  • Use the package.json script as the container command so the PATH is the same as on your laptop.
  • Keep the start command and the build output mode (next start or standalone) in one place, reviewed together.

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.