unraid.net Paid content

When a Docker build fails or a container exits immediately, the fix usually starts with reading the error correctly. Docker separates two phases: build time (the image is being created from your Dockerfile) and run time (a container is starting from a finished image). Most errors belong clearly to one phase, and identifying the phase narrows the cause quickly. This guide walks through how to read the output, isolate the layer where things break, and use Docker CLI commands to inspect and debug.

First: Decide Which Phase Is Failing

If you are unsure, run the build and the container separately rather than chaining them. That alone tells you which half of the problem you own.

Reading Docker Build Output

Build output is sequential. The failure is almost always at the last step shown, not the first. Docker prints each instruction and its result; the first non-zero exit stops the build.

Common build errors and their root causes

COPY failed: file not found in build context The path you referenced does not exist relative to the build context you passed. Check that:

• The file is inside the directory given to docker build (often .).
• A .dockerignore file is not excluding it.
• You are not copying from outside the context (Docker cannot reach parent directories).

RUN command returns exit code 1 (or another non-zero) The command inside the container failed. This is usually an application-level problem, not a Docker problem: a missing package, a wrong path, a failed download, or a command that assumes a shell feature your base image lacks. Read the lines above the error — the real message is often printed there.

failed to solve / buildkit errors BuildKit reports the failing instruction and often a hint. Treat the hint as a starting point, not a guarantee. Reproduce the failing command manually by running an interactive container from the previous stage's image.

no matching manifest for <platform> The image you are pulling does not publish a variant for your architecture. Confirm the image supports your platform, or build for the platform the image provides.

A practical build-debug loop

1. Build with plain output so steps are visible: docker build -t myapp .
2. Note the last successful step.
3. Start an interactive shell from that intermediate image (or from the base image) and run the failing command by hand.
4. Fix the Dockerfile, rebuild, repeat.

If the build is slow, reorder instructions so frequently changing steps come last — but do this only after the error is fixed, not while debugging.

Reading Container Startup Failures

A container that exits immediately is doing what it was told: its main process ended. Docker does not keep a container alive if its entrypoint/command finishes.

Step 1: Get the exit code

docker ps -a

Look at the STATUS column. An exit code of 0 usually means the process completed successfully but was not meant to be a long-running service. Codes like 1, 127, or 137 point to different causes:

• 127 — command not found (wrong entrypoint, missing binary, or a shell path issue).
• 1 — general application error; check logs.
• 137 — the process was killed, often out of memory or a manual stop.

Step 2: Read the logs

docker logs <container_id>

If the logs are empty, the process may have failed before producing output — a strong sign of a bad entrypoint or a missing executable. Confirm what the container is actually trying to run:

docker inspect <container_id>

Check the Config.Cmd and Config.Entrypoint fields. A common mistake is an entrypoint that references a file not present in the final image, or a shell form that swallows arguments.

Step 3: Run it interactively

Override the entrypoint to get a shell and explore the container's filesystem:

docker run -it --entrypoint sh <image>

From inside, verify the binary exists, the working directory is what you expect, and environment variables are set. This is the fastest way to separate "the image is wrong" from "the runtime configuration is wrong."

Step 4: Check runtime configuration

If the image works interactively but fails normally, the problem is likely configuration:

• Missing environment variables — the app exits when a required variable is absent.
• Port conflicts — the container starts but the host port is already in use; the error appears in docker run output.
• Volume mounts — a mount can hide files the image expected, or point at an empty host directory.
• Networking — the container cannot reach a dependency it needs at startup.

Isolating Dockerfile vs. Image vs. Runtime

Use this decision path:

1. Does the build succeed? If no, the problem is in the Dockerfile or build context.
2. Does the image run interactively? If yes but the normal run fails, the problem is runtime configuration (env, ports, volumes, command).
3. Does it fail in both? The image itself is incomplete — a missing dependency or file baked in at build time.
4. Does it work locally but fail elsewhere? Compare environment, architecture, and mounted data between the two environments.

When to Consult Docker Docs

The official documentation at docs.docker.com is the right reference for:

• CLI command flags — exact options for docker build, docker run, docker inspect, and docker logs.
• Dockerfile instruction semantics — how COPY, RUN, ENTRYPOINT, and CMD interact, especially the difference between shell and exec form.
• Build context and .dockerignore — what gets sent to the daemon and what is excluded.
• Registry and authentication — pull failures tied to login or access.

Use the docs to confirm behavior, not to guess at it. Error messages are usually literal; the documentation explains the rules behind them.

A Reusable Debugging Checklist

• [ ] Identify the failing phase: build or run.
• [ ] For builds, read the last STEP and the lines above the error.
• [ ] For runs, get the exit code with docker ps -a.
• [ ] Read docker logs before changing anything.
• [ ] Inspect Entrypoint and Cmd with docker inspect.
• [ ] Reproduce interactively with --entrypoint sh.
• [ ] Check env vars, ports, and volume mounts.
• [ ] Confirm the image supports your platform.
• [ ] Only then edit the Dockerfile or run command.

Most Docker errors are not mysterious once you know which phase failed and where to look. Read the last step, check the exit code, read the logs, and reproduce interactively. That sequence resolves the large majority of build and startup failures without guesswork.