Skip to content

Cache misses using a remote build cache when sharing docker targets #3878

Description

@tg-freigmbh

Contributing guidelines

I've found a bug and checked that ...

  • ... the documentation does not mention anything about my problem
  • ... there are no open or closed issues that are related to my problem

Description

We are affected by an interesting remote cache problem. We get cache hits for each individual target, but not when multiple targets are build at the same time.
In the linked repo:

  1. set variable registry to your cache repo
  2. docker buildx bake
  3. docker builder prune -f
  4. docker buildx bake --progress=plain alpha beta

This will usually result in something like:

#14 [beta build 3/3] RUN echo "This should been optimized away beta"
#14 0.266 This should been optimized away beta
#14 DONE 0.3s
#11 [alpha build 3/3] RUN echo "This should been optimized away alpha"
#11 CACHED

So a cache hit for one build but not for the other.
However executing
2. docker buildx bake
3. docker builder prune -f
4. docker buildx bake --progress=plain alpha
5. docker builder prune -f
6. docker buildx bake --progress=plain beta
Will result in a full cache hit and never print the statement

Expected behaviour

docker buildx bake alpha beta
should have the same cache hits as

docker buildx bake alpha
docker buildx bake beta

Actual behaviour

1 Target gets a cache hit, the other targets dont.

Buildx version

github.com/docker/buildx v0.33.0-desktop.1 7f91f038ac14cbf5c4b2a6b76470860814424da1

Docker info

Client:
 Version:    29.4.3
 Context:    desktop-linux
 Debug Mode: false
 Plugins:
  agent: Docker AI Agent Runner (Docker Inc.)
    Version:  v1.57.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-agent.exe
  ai: Docker AI Agent - Ask Gordon (Docker Inc.)
    Version:  v1.20.2
    Path:     C:\Program Files\Docker\cli-plugins\docker-ai.exe
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.33.0-desktop.1
    Path:     C:\Program Files\Docker\cli-plugins\docker-buildx.exe
  compose: Docker Compose (Docker Inc.)
    Version:  v5.1.3
    Path:     C:\Program Files\Docker\cli-plugins\docker-compose.exe
  debug: Get a shell into any image or container (Docker Inc.)
    Version:  0.0.47
    Path:     C:\Program Files\Docker\cli-plugins\docker-debug.exe
  desktop: Docker Desktop commands (Docker Inc.)
    Version:  v0.3.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-desktop.exe
  dhi: CLI for managing Docker Hardened Images (Docker Inc.)
    Version:  v0.0.3
    Path:     C:\Program Files\Docker\cli-plugins\docker-dhi.exe
  extension: Manages Docker extensions (Docker Inc.)
    Version:  v0.2.31
    Path:     C:\Program Files\Docker\cli-plugins\docker-extension.exe
  init: Creates Docker-related starter files for your project (Docker Inc.)
    Version:  v1.4.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-init.exe
  mcp: Docker MCP Plugin (Docker Inc.)
    Version:  v0.42.1
    Path:     C:\Program Files\Docker\cli-plugins\docker-mcp.exe
  model: Docker Model Runner (Docker Inc.)
    Version:  v1.1.37
    Path:     C:\Program Files\Docker\cli-plugins\docker-model.exe
  offload: Docker Offload (Docker Inc.)
    Version:  v0.5.89
    Path:     C:\Program Files\Docker\cli-plugins\docker-offload.exe
  pass: Docker Pass Secrets Manager Plugin (beta) (Docker Inc.)
    Version:  v0.0.27
    Path:     C:\Program Files\Docker\cli-plugins\docker-pass.exe
  sandbox: Docker Sandbox (Docker Inc.)
    Version:  v0.12.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-sandbox.exe
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc.)
    Version:  0.6.0
    Path:     C:\Program Files\Docker\cli-plugins\docker-sbom.exe
  scout: Docker Scout (Docker Inc.)
    Version:  v1.20.4
    Path:     C:\Program Files\Docker\cli-plugins\docker-scout.exe

Server:
 Containers: 34
  Running: 34
  Paused: 0
  Stopped: 0
 Images: 55
 Server Version: 29.4.3
 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Discovered Devices:
  cdi: docker.com/gpu=webgpu
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 nvidia runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 77c84241c7cbdd9b4eca2591793e3d4f4317c590
 runc version: v1.3.5-0-g488fc13e
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.6.114.1-microsoft-standard-WSL2
 Operating System: Docker Desktop
 OSType: linux
 Architecture: x86_64
 CPUs: 24
 Total Memory: 31.28GiB
 Name: docker-desktop
 ID: 28518f49-cc95-4c07-bc7c-7a5805d4d3e3
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 No Proxy: hubproxy.docker.internal
 Labels:
  com.docker.desktop.address=npipe://\\.\pipe\docker_cli
 Experimental: false
 Insecure Registries:
  hubproxy.docker.internal:5555
  ::1/128
  127.0.0.0/8
 Registry Mirrors:
  https://docker.freigmbh.de/
 Live Restore Enabled: false
 Default Address Pools:
   Base: 192.168.128.0/17, Size: 26
 Firewall Backend: iptables

Builders list

NAME/NODE           DRIVER/ENDPOINT     STATUS    BUILDKIT   PLATFORMS
default             docker                                   
 \_ default          \_ default         running   v0.29.0    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)
desktop-linux*      docker                                   
 \_ desktop-linux    \_ desktop-linux   running   v0.29.0    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)

Configuration

I made a reproducer here:
https://github.com/tg-freigmbh/repro-bake/tree/main

Build logs


Additional info

This seems to be very much tight to the docker buildtarget "build".
Something along the lines that due to the ARG SVC it could result in 2 different images, but in fact it doesnt.

For our productive problem we were able to solve this by inlining the target "build" into "runtime"-> Since docker lazy resolves ARG and shares everything anyway this seems currently as a good workaround without downsides.

Activity

  1. perfx commented on Oct 1, 2026

    @perfx

    I hit this too and narrowed it down a bit. It doesn't seem to be specific to a shared stage or to registry caches. It reproduces with type=local caches whenever two targets share a local mount: the same main context directory, or the same named context. Each target exports to its own cache. On every rebuild with a fresh builder, one of the two targets re-runs a step it should have taken from cache, and which target misses varies between runs. If the second target points at the same directory through a symlink, so the mounts no longer have the same path, both targets hit on every rebuild.

    That matches detectSharedMounts in build/build.go, which puts requests whose local mounts have the same (name, dir) into one shared session. In your repro, alpha and beta share contexts = { api = "./api" }, which is the same condition. This is a guess from reading the code; I haven't traced where the cache match gets lost.

    Self-contained script (bash, docker-container driver, no registry). There is no shared stage; the only RUN uses a per-target ARG:

    repro.sh
    #!/usr/bin/env bash
    # Two bake targets, each with its own local cache, rebuilt on a fresh builder.
    # Prints which targets re-ran a step that should have come from cache.
    set -euo pipefail
    cd "$(mktemp -d)"
    mkdir -p ctx ctx-a ctx-b shared
    echo a > ctx/f; echo a > ctx-a/f; echo a > ctx-b/f; echo s > shared/f
    ln -s ctx ctx-link
    
    cat > Dockerfile <<'EOF'
    FROM alpine:3.20
    ARG T
    COPY f /f
    RUN echo "EXECUTED $T" && date > /out
    EOF
    
    cat > Dockerfile.named <<'EOF'
    FROM alpine:3.20
    ARG T
    COPY --from=shared f /f
    RUN echo "EXECUTED $T" && date > /out
    EOF
    
    # $1 = scenario name, $2 = context of a, $3 = context of b, $4 = dockerfile, $5 = named contexts
    bakefile() {
      cat <<EOF
    group "default" { targets = ["a", "b"] }
    target "_common" {
      dockerfile = "$PWD/$4"
      output     = ["type=cacheonly"]
      contexts   = { $5 }
    }
    target "a" {
      inherits   = ["_common"]
      context    = "$2"
      args       = { T = "a" }
      cache-from = ["type=local,src=$PWD/cache-$1-a"]
      cache-to   = ["type=local,dest=$PWD/cache-$1-a,mode=max"]
    }
    target "b" {
      inherits   = ["_common"]
      context    = "$3"
      args       = { T = "b" }
      cache-from = ["type=local,src=$PWD/cache-$1-b"]
      cache-to   = ["type=local,dest=$PWD/cache-$1-b,mode=max"]
    }
    EOF
    }
    
    scenario() {
      bakefile "$@" > "$1.hcl"
      for run in 1 2 3 4; do
        docker buildx create --name "repro-$1-$run" --driver docker-container >/dev/null
        docker buildx bake --builder "repro-$1-$run" --progress=plain \
          --allow=fs.read="$PWD" --allow=fs.write="$PWD" -f "$1.hcl" > "$1-$run.log" 2>&1
        docker buildx rm "repro-$1-$run" >/dev/null 2>&1
        reran=$(grep -oE '^#[0-9]+ [0-9.]+ EXECUTED [ab]' "$1-$run.log" | awk '{print $4}' | sort | tr '\n' ' ' || true)
        echo "$1 run $run (fresh builder): re-ran: ${reran:-none}"
      done
    }
    
    scenario shared-context ./ctx ./ctx Dockerfile ""
    scenario symlinked-context ./ctx ./ctx-link Dockerfile ""
    scenario shared-named-context ./ctx-a ./ctx-b Dockerfile.named 'shared = "./shared"'

    Output (run 1 is the cold build that fills each cache):

    shared-context run 1 (fresh builder): re-ran: a b 
    shared-context run 2 (fresh builder): re-ran: b 
    shared-context run 3 (fresh builder): re-ran: b 
    shared-context run 4 (fresh builder): re-ran: b 
    symlinked-context run 1 (fresh builder): re-ran: a b 
    symlinked-context run 2 (fresh builder): re-ran: none
    symlinked-context run 3 (fresh builder): re-ran: none
    symlinked-context run 4 (fresh builder): re-ran: none
    shared-named-context run 1 (fresh builder): re-ran: a b 
    shared-named-context run 2 (fresh builder): re-ran: a 
    shared-named-context run 3 (fresh builder): re-ran: a 
    shared-named-context run 4 (fresh builder): re-ran: b 
    

    Versions: buildx v0.30.1-desktop.1, BuildKit v0.33.1 (moby/buildkit:buildx-stable-1), Docker Desktop 29.1.2, macOS arm64. detectSharedMounts is unchanged on master (42b3f95). We see the same thing in GitHub Actions with type=gha caches and two compose services built from the same context directory.

    Workaround until there's a fix: give each target its own context path (a symlink to the shared directory is enough).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions