🚨 Docker Error Guide: 'Forbidden path outside the build context' — COPY/ADD Beyond the Context

Overview

Docker builds only see files inside the build context — the directory (or URL) you pass as the final argument to docker build. A COPY or ADD whose source resolves outside that root is rejected, because the daemon never received those files:

COPY ../shared/config.yaml /app/config.yaml
Error: Forbidden path outside the build context: ../shared/config.yaml ()

The BuildKit phrasing is similar:

failed to compute cache key: "/shared/config.yaml" not found: 
forbidden path outside the build context

Symptoms

• docker build fails at a COPY/ADD line that references ../ or an absolute path.
• The Dockerfile builds from one directory but fails from another because the context changed.
• docker compose build fails while a direct docker build in a different directory works.
• A file that exists on disk is reported as not found or forbidden.

Common Root Causes

• COPY ../something — the source climbs above the context root, which is never sent to the daemon.
• An absolute host path in COPY/ADD — COPY /etc/app/config /app/ refers to the host, not the context.
• Wrong context argument — docker build -f app/Dockerfile . vs building from inside app/ changes what ../ means.
• Compose build.context set too narrow — the service context excludes files the Dockerfile copies.
• Symlinks pointing outside the context — the resolved target lies beyond the root.

Diagnostic Workflow

Identify the context root and the Dockerfile location for the failing build:

# context is the LAST argument; -f is the Dockerfile path
docker build -f app/Dockerfile -t myapp:1.4.2 .

List what is actually inside the context that Docker sends:

ls -la .
cat .dockerignore 2>/dev/null

Confirm the offending source relative to the context:

grep -nE '^\s*(COPY|ADD)\s' app/Dockerfile

For Compose, check the declared context and dockerfile:

docker compose config | grep -A3 'build:'

Reproduce with an explicit, correct context and read the failing step:

docker build -t myapp:1.4.2 . 2>&1 | tail -20

Example Root Cause Analysis

A monorepo had this layout, with a service Dockerfile trying to reuse shared config a level up:

repo/
  shared/config.yaml
  service-a/Dockerfile   # COPY ../shared/config.yaml /app/config.yaml

Running docker build -t svc-a:1.4.2 . from inside service-a/ failed with Forbidden path outside the build context: ../shared/config.yaml. The context was service-a/, so ../shared sat outside it and was never sent to the daemon.

The fix moved the context up to the repo root so both the Dockerfile and the shared files were inside it, and made the COPY paths relative to that root:

# from repo/
docker build -f service-a/Dockerfile -t svc-a:1.4.2 .

COPY shared/config.yaml /app/config.yaml
COPY service-a/ /app/

Now every source is inside the context root, so the build succeeds. A .dockerignore was added to exclude unrelated directories and keep the context small.

Prevention Best Practices

• Keep every COPY/ADD source inside the context; never use ../ or absolute host paths in a Dockerfile.
• For monorepos, set the context to the repository root and reference files with paths relative to it (-f path/to/Dockerfile .).
• Add a .dockerignore to trim a large context so builds stay fast even with a wide root.
• In Compose, set build.context to the directory that contains all files the Dockerfile needs.
• Prefer multi-stage builds or bind mounts (--mount=type=bind) over reaching outside the context for shared assets.
• Lint your Dockerfiles with the free Dockerfile validator to catch context and COPY issues early.

Quick Command Reference

grep -nE '^\s*(COPY|ADD)\s' Dockerfile     # find sources that escape context
cat .dockerignore                           # what is excluded
docker build -f service-a/Dockerfile -t myapp:1.4.2 .   # context = repo root
docker compose config | grep -A3 'build:'   # Compose context/dockerfile

Conclusion

Forbidden path outside the build context means a COPY or ADD points to files Docker never received, because they live above or outside the context root. Widen the context to include everything the Dockerfile needs and make source paths relative to it, or restructure with multi-stage builds and bind mounts. A .dockerignore keeps the widened context lean. Validate your Dockerfiles early and see more build fixes in the Docker guides.