Why my docker build fails — 3 causes and how to check each one

docker build has exactly two outcomes: everything works, or a wall of red text where you can't tell which line is guilty.
Good news: 90% of failures come down to three causes. And each has a signature symptom you can spot in ten seconds.
First the skill, then the causes.
Start by finding which step failed
Docker builds the image step by step from your Dockerfile, and every step is labelled in the output. Don't look for the first red line — look for the last line before the error:
=> [4/6] RUN npm ci
=> ERROR [5/6] RUN npm run build
Step five failed, not step one — so dependencies installed fine and the problem is in the project build. That narrows the search enormously. The general technique for reading these walls of text is in how to read an error message.
Cause 1: you're copying the entire project into the image
The most common and the least visible.
Symptom. Near the top of the output, a line like transferring context: 480.5MB and a long pause. Builds take minutes, the cache never hits, and sometimes it dies on a cryptic binary error.
Why. COPY . . drags in everything in the folder: node_modules, .git, downloaded models, .env. And if node_modules was built on a Mac while the image is Linux, you now have binaries for someone else's OS inside. The app either won't start or fails on a module that is "definitely installed".
How to check. Look at the context size in that first line. More than a couple of dozen megabytes for a normal project is already suspicious.
How to fix. Put a .dockerignore next to your Dockerfile:
node_modules
.git
dist
.env
*.log
Same syntax as .gitignore. Bonus: your secrets stop riding along into the image — an image you will probably push somewhere.
Cause 2: the image was built for a different architecture
A modern classic, since nearly everyone's laptop is ARM now.
Symptom. It built and ran locally, then on the server: exec format error. Or when pulling: no matching manifest for linux/amd64.
Why. Your M-series Mac builds for arm64, while a normal cloud server is amd64. Those are different binary formats — the system literally doesn't recognise the file it's handed. The error appears at run time, not build time, which is why people hunt for it in the wrong place.
How to check. One command:
docker image inspect your-image --format '{{.Architecture}}'
If it says arm64 and your server is a regular one, there's your answer.
How to fix. State the platform explicitly:
docker build --platform linux/amd64 -t your-image .
It builds slower (emulation), but it runs. If you need the image on both, build for both at once with docker buildx build --platform linux/amd64,linux/arm64.
This same cause explains half the cases of works locally but not in production.
Cause 3: the build ran out of memory
Symptom. A step dies with no real message: Killed, or exit code: 137, or the process just vanishes during npm run build.
Why. 137 isn't your program's exit code. It's 128 plus 9: the process was killed by signal 9, i.e. by the system for using too much memory. Usually during a frontend build, where the bundler unfolds the project in memory and hits the limit Docker was given.
How to check. On macOS and Windows, Docker lives in a VM with a fixed memory allowance. Open Docker Desktop settings, Resources section: if it says 2 GB, that's not enough for almost any modern frontend.
How to fix. In order:
- Raise the memory limit in Docker settings to 4–8 GB.
- If it fails in CI where the settings aren't yours, shrink the build's appetite: build the frontend separately and copy only the finished files into the image (multi-stage build).
- Check you aren't hauling junk into the image — see cause 1, which quietly eats memory too.
Why does it fail in CI but build fine locally?
Because locally you have a warm cache and a different machine. In CI every build starts from scratch: none of your layers, often less memory, and a different architecture. To reproduce it at home, build with --no-cache and an explicit platform. The error usually shows up right away.
What does exit code 1 on a RUN step mean?
That the command you wrote in RUN failed — not Docker. RUN npm ci exiting with 1 is an npm error, and its actual text is further up the log. Docker is just the messenger here: it stops the build because any non-zero code on a step counts as failure. For what an image even is and how it differs from a container, see what Docker is; for how it compares to a virtual machine, Docker vs VM.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





