🐳 Reading Docker Build Errors

Root cause: the lockfile was never copied into the build context before npm ci ran.

Reading the Dockerfile excerpt at the bottom of the log: line 5 copies only package.json, then line 6 runs npm ci. Unlike npm install, npm ci is strict — it requires an existing package-lock.json (or npm-shrinkwrap.json) to install from, and refuses to run without one. The error npm error code EUSAGE means "you used this command incorrectly", not a network or registry problem.

The fix: change COPY package.json ./ to COPY package*.json ./ so both package.json and package-lock.json are copied before the install step. This is also a common Docker layer-caching pattern: copying just the manifest files first (before the rest of the source) lets Docker reuse the cached npm ci layer when only application code changes.

Log-reading tip: Buildx output shows the failing step with ERROR, then a ------ block with the command's own stderr, then the Dockerfile lines around the failure, then a final one-line summary starting with ERROR: failed to solve:. Read top to bottom in that order to go from "what command failed" to "why".

A one-character typo: alpin instead of alpine.

"failed to resolve source metadata for ... not found" means Docker successfully contacted the registry, but the registry has no image with that exact name and tag. This is different from a network failure (which would show a timeout or DNS error) — the registry answered, it just said "I don't have this".

Reading strategy: when a build fails at the very first FROM step with a "not found" message, always re-read the base image string character by character before assuming a registry or network issue — a single typo in the tag is the most common cause.

How to describe this to a colleague: "The build's failing because the base image tag doesn't exist — looks like a typo, alpin instead of alpine." Note the useful distinction between image (e.g. node), tag (e.g. 20-alpine), and digest (a content hash, e.g. @sha256:...) — all three are ways to reference a specific image.

The builder stage "succeeded" but never created the expected output path.

A multi-stage Dockerfile runs each stage independently, then COPY --from=<stage> copies files from one stage's filesystem into another. Here, the log shows the builder stage's npm run build step completed with exit code 0 (no red ERROR against it) — but that only means the command didn't crash, not that it produced the files you expect.

Common real causes:

• The build tool's actual output directory is build/ or out/, not dist/ (check the framework's config, e.g. Vite's outDir)
• The build script exits 0 even when it silently skips work (e.g. missing environment variables cause it to no-op)
• A working directory mismatch between stages — the WORKDIR in builder differs from where the build tool actually wrote its files

Debugging move: temporarily add RUN ls -la /app right after the build step in the builder stage (or build just that stage with docker build --target builder . and docker run --rm -it <image> sh to inspect it) to see what was actually produced before trusting the COPY --from path.

How to describe this to a colleague: "The build step itself passes, but the copy from the builder stage can't find /app/dist — I think the build output is going somewhere else, not that the build actually failed."