Docker breaking changes, updated weekly

Every verified Docker trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all Docker traps.

1. fg-0254· added 2026-10-15· last checked 2026-10-15

   buildx --load with two platforms fails with 'docker exporter does not currently support exporting manifest lists'

   Symptom

   ERROR: docker exporter does not currently support exporting manifest lists

   Fix

   Turn on the containerd image store, or load one platform at a time for local tests and push the multi-platform build to a registry. Switching stores hides images and containers created under the old store until you switch back.

2. fg-0256· added 2026-10-15· last checked 2026-10-15

   Container cannot reach a service on the host through localhost, and host.docker.internal does not resolve on Linux

   Symptom

   connect ECONNREFUSED 127.0.0.1:5432 from inside the container

   Fix

   Map host.docker.internal to host-gateway and make the host service listen on an address the bridge can reach. Between Compose services, connect by service name instead.

3. fg-0257· added 2026-10-15· last checked 2026-10-15

   depends_on starts the app before the database accepts connections, so first boot fails

   Symptom

   ECONNREFUSED or 'the database system is starting up' on first docker compose up, gone after a restart

   Fix

   Give the dependency a healthcheck and use the long depends_on form with condition service_healthy.

4. fg-0258· added 2026-10-15· last checked 2026-10-15

   Docker layer cache with type=gha never hits when one workflow builds several images

   Symptom

   Every run rebuilds from the first RUN step although cache-from type=gha is set

   Fix

   Give each image its own scope and export with mode=max.

5. fg-0259· added 2026-10-15· last checked 2026-10-15

   docker run --env-file keeps the quote characters that Compose and shells strip from values

   Symptom

   The variable arrives in the container as "hello world" with the quotes included

   Fix

   Keep a separate unquoted file for docker run --env-file, pass the values with -e, or start the container through Compose.

6. fg-0260· added 2026-10-15· last checked 2026-10-15

   docker volume prune reports 'Total reclaimed space: 0B' and leaves every unused named volume

   Symptom

   Total reclaimed space: 0B

   Fix

   List the unused volumes first, then prune with --all when you really mean every unused volume, including named ones.

7. fg-0262· added 2026-10-15· last checked 2026-10-15

   GitHub Actions Docker build fails with 'This legacy service is shutting down, effective April 15, 2025'

   Symptom

   ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP.

   Fix

   Unpin the Buildx and BuildKit versions in the workflow or raise them to at least Buildx 0.21.0 and BuildKit 0.20.0.

8. fg-0264· added 2026-10-15· last checked 2026-10-15

   Image built with buildx runs locally but AWS Lambda rejects it because the push is an image index

   Symptom

   Lambda create-function or update-function-code rejects an image that pulls and runs fine with docker run

   Fix

   Turn off default attestations for images that go to runtimes needing one plain manifest, and build for exactly one platform.

9. fg-0265· added 2026-10-15· last checked 2026-10-15

   network_mode: host on Docker Desktop for Mac does not expose the app on the Mac's localhost

   Symptom

   curl localhost:3000 on the Mac is refused while the container logs show the server listening

   Fix

   Publish ports with -p or ports instead of host networking, or turn the feature on in settings on 4.34 or later.

10. fg-0255· added 2026-10-15· last checked 2026-10-15

    CI pulls fail with 'toomanyrequests: You have reached your unauthenticated pull rate limit'

    Symptom

    toomanyrequests: You have reached your unauthenticated pull rate limit

    Fix

    Log in to Docker Hub before pulling in CI, cache or mirror base images in your own registry, and avoid pulling the same image in every job.

11. fg-0261· added 2026-10-15· last checked 2026-10-15

    FROM a locally built image tries to pull from docker.io when the buildx builder uses the docker-container driver

    Symptom

    load metadata for docker.io/library/my_base_image:latest fails although docker images lists my_base_image

    Fix

    Build images that depend on local images with the default docker builder, push the base image to a registry first, or switch to the containerd image store. Check which builder is active with docker buildx ls.

12. fg-0263· added 2026-10-15· last checked 2026-10-15

    Image built on an Apple Silicon Mac crashes with 'exec format error' on an amd64 server

    Symptom

    exec /usr/local/bin/docker-entrypoint.sh: exec format error

    Fix

    Set the target platform explicitly when building images for servers, and set platform in Compose for images that only ship amd64 so Desktop runs them under emulation.

13. fg-0266· added 2026-10-15· last checked 2026-10-15

    Non-root container gets 'Permission denied' writing to a mounted volume

    Symptom

    EACCES: permission denied, open '/data/app.db'

    Fix

    Create and chown the mount path in the Dockerfile before switching USER, then remove the old volume so it is recreated with the new owner. For bind mounts, run the container with the UID that owns the host directory.

14. fg-0268· added 2026-10-15· last checked 2026-10-15

    Variables from the Compose project dotenv file are substituted into the YAML but missing inside the container

    Symptom

    printenv inside the container does not list the variable

    Fix

    Reference each variable under environment, or point the service at the file with env_file.

15. fg-0267· added 2026-10-15· last checked 2026-10-15

    Tools on the Docker socket fail with 'client version 1.24 is too old' after upgrading to Engine 29

    Symptom

    Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version

    Fix

    Upgrade the tool to a release that negotiates or speaks API 1.44 or later, or move the engine to 29.3 or later where the floor is 1.40, which covers clients pinned at 1.40 and above. As a temporary stopgap only, operators in the Traefik thread set DOCKER_MIN_API_VERSION=1.24 on the dockerd service through a systemd override; Docker's only mention of that variable is a commented-out block on the engine deprecation page, so remove it once the tool is upgraded.