EC
layer already exists
DockerINFOBuildHIGH confidence

A pushed image layer already exists in the remote registry

What this means

This is not an error, but an informational message that appears during a 'docker push'. It indicates that a specific layer of the image you are pushing already exists in the remote registry. Docker is efficient and will not re-upload the same data twice.

Why it happens
  1. 1You are pushing a new tag of an image that shares base layers with a previously pushed tag.
  2. 2Another user or CI/CD process has already pushed the same base image or layers to the registry.
  3. 3The push was interrupted and is being retried; Docker is skipping the layers that were successfully uploaded before the interruption.
  4. 4This is the normal, expected behavior of the Docker push process.
How to reproduce

You build an image, push it, then make a small change to the last layer and push it again.

trigger — this will error
trigger — this will error
# Build and push an image
docker build -t my-registry/my-app:1.0 .
docker push my-registry/my-app:1.0

# Add a file, then rebuild and push again
# (Only the last layer will be new)
docker build -t my-registry/my-app:1.1 .
docker push my-registry/my-app:1.1

expected output

The push refers to repository [my-registry/my-app]
a1b2c3d4e5f6: Layer already exists
f1e2d3c4b5a6: Layer already exists
...
z9y8x7w6v5u4: Pushed
1.1: digest: sha256:... size: ...

Fix 1

No Fix Needed

WHEN This message appears during a 'docker push'.

No Fix Needed
# This is normal output
# No action is required.

Why this works

This message confirms that Docker's layer caching and deduplication is working correctly, saving you time and bandwidth by not re-uploading unchanged layers.

Fix 2

Squash Image to Force Re-upload

WHEN You suspect layer corruption in the registry and want to force a re-upload of the entire image (very rare).

Squash Image to Force Re-upload
# Build the image by squashing all layers into one
docker build --squash -t my-registry/my-app:1.1-squashed .
docker push my-registry/my-app:1.1-squashed

Why this works

Squashing creates a brand new, single layer that does not exist in the registry, forcing Docker to upload the entire image content. This is generally not recommended as it breaks layer caching.

What not to do

✕ Treat 'Layer already exists' as an error.

It is a sign of a healthy, efficient process. Alerting on this message will create constant noise and false positives in your CI/CD pipelines.

Sources
Official documentation ↗

Docker 'push' command documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Docker errors