docker build: 'COPY failed: file not found in build context' or 'failed to solve: failed to compute cache key: "/app/package.json": not found'. Why can't Docker see a file that exists?

Cause: docker build can only read files from the build context, the directory (or URL) given as the last argument, usually '.'. Paths in COPY and ADD are resolved relative to that context, not relative to the Dockerfile's location and not relative to your shell's current directory. The usual reasons for 'not found': building from the wrong directory (or with -f pointing at a Dockerfile in a subfolder while the context is elsewhere), a COPY path that goes outside the context (COPY ../shared ... never works), the file being excluded by .dockerignore, a typo or wrong letter case (Linux paths are case-sensitive), or the file being generated by a step that didn't run before the build (for example a missing build output folder in CI). Fix: 1. Check what you pass as context: docker build -f docker/Dockerfile . uses the current directory as context; write COPY paths relative to that directory. 2. Read .dockerignore: patterns like * with exceptions, **/dist, or *.json can exclude the file. Add an exception (!package.json) or remove the pattern. 3. If the files live outside the current context, build from a higher directory (docker build -f app/Dockerfile ..), or with BuildKit use named contexts (docker buildx build --build-context shared=../shared ... and COPY --from=shared ...). 4. In CI, make sure the step that produces the file (npm run build, a checkout of submodules, a downloaded artifact) runs before docker build and in the same working directory. 5. In docker compose, check build.context and build.dockerfile in compose.yaml; the context path is relative to the compose file. Verify: re-run with docker build --progress=plain to see the context transfer size and the failing step, then confirm the build passes the COPY step. Sources: https://docs.docker.com/build/concepts/context/ https://docs.docker.com/reference/dockerfile/