How to fix failed to solve: failed to prepare cache mount: failed to mount in Docker

The most common fix is to explicitly set permissions on the cache mount. By default, BuildKit creates cache mounts with restrictive permissions that may not work on all systems.

Update your Dockerfile:

# Before (may fail):
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt

# After (with explicit permissions):
RUN --mount=type=cache,mode=0777,target=/root/.cache/pip pip install -r requirements.txt

This is especially important on macOS and Windows Docker Desktop where the default mode may prevent mounting.

Cache mounts require BuildKit and the appropriate Dockerfile syntax version. Add this directive at the very beginning of your Dockerfile:

# syntax=docker/dockerfile:1

FROM python:3.11
RUN --mount=type=cache,mode=0777,target=/root/.cache/pip pip install -r requirements.txt

Alternatively, you can use the experimental syntax:

# syntax=docker/dockerfile:experimental

Note: The syntax directive must be the first line in the file (before any comments or FROM instructions).

If your Dockerfile runs as a non-root user, you need to specify matching uid/gid values for the cache mount:

# syntax=docker/dockerfile:1

FROM node:18
USER node

# Cache mount with uid/gid matching the 'node' user (typically 1000:1000)
RUN --mount=type=cache,target=/home/node/.npm,uid=1000,gid=1000 npm ci

To find the correct uid/gid for your user, you can run:

docker run --rm node:18 id node
# Output: uid=1000(node) gid=1000(node) groups=1000(node)

Cache mounts require BuildKit to be enabled. If you are using Docker Desktop, BuildKit is enabled by default. For Docker Engine, you can enable it by:

Option 1: Set environment variable (per-command)

DOCKER_BUILDKIT=1 docker build -t myapp .

Option 2: Configure Docker daemon (permanent)
Add to /etc/docker/daemon.json:

{
  "features": {
    "buildkit": true
  }
}

Then restart Docker:

sudo systemctl restart docker

Option 3: Use docker buildx (recommended)

docker buildx build -t myapp .

Sometimes corrupted cache data can cause mount failures. Clear the BuildKit cache and try again:

# Clear all BuildKit cache
docker builder prune -a

# Or more selectively, remove only build cache
docker builder prune --filter type=exec.cachemount

After pruning, rebuild your image:

docker build --no-cache -t myapp .

Some package managers (like apt) require exclusive access to their cache. If you see errors related to concurrent access or lock files, use the sharing=locked option:

# syntax=docker/dockerfile:1

FROM ubuntu:22.04

# Use locked sharing for apt cache
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y curl

The sharing modes are:
- shared (default): Multiple builds can access simultaneously
- private: Each build gets its own cache instance
- locked: Only one build can access at a time (waits for lock)

If you have multiple Dockerfiles or build jobs that should not share cache, use unique cache IDs:

# In Dockerfile.frontend
RUN --mount=type=cache,id=frontend-npm,target=/root/.npm npm ci

# In Dockerfile.backend
RUN --mount=type=cache,id=backend-npm,target=/root/.npm npm ci

For CI/CD pipelines, you can parameterize the cache ID:

ARG CACHE_ID=default
RUN --mount=type=cache,id=${CACHE_ID}-pip,target=/root/.cache/pip pip install -r requirements.txt

Build with:

docker build --build-arg CACHE_ID=$CI_JOB_ID -t myapp .

If you have user namespace remapping enabled (userns-remap in Docker daemon config), cache mounts may fail with permission errors due to uid/gid mapping.

Check if userns-remap is enabled:

docker info | grep -i remap

If enabled, you have a few options:

Option 1: Disable userns-remap for builds (not recommended for production)
Remove or comment out the userns-remap setting in /etc/docker/daemon.json.

Option 2: Map correct uid/gid in your Dockerfile
Account for the remapped uid/gid values in your cache mount configuration.

Option 3: Use docker buildx with a dedicated builder

docker buildx create --name mybuilder --use
docker buildx build -t myapp .

As a last resort for debugging or urgent builds, you can disable BuildKit entirely. Note that this will disable all cache mount functionality:

DOCKER_BUILDKIT=0 docker build -t myapp .

Your build will proceed without cache mounts, using traditional Docker layer caching. This is useful for determining if BuildKit itself is the issue.

Once your build works, re-enable BuildKit and systematically test which cache mount is causing problems.