Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker push says the tag does not exist

Errortag does not exist: <name>:<tag>

Short answer

docker push sends exactly the name you type, and that name must already exist on your machine. The error means no local image carries it. Run docker image ls, then create the name you want with docker tag, including the registry host for a private registry, and push again.

  • Applies to Docker Engine 28 and 29, Docker CLI 28 and 29
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List local images and compare the exact repository and tag column with the name you passed to push. They must match character for character.

    docker image ls
  2. 2Match what you see, then jump to its fix

    1. 1docker image ls shows the image, but under another repository name or tag than the one in the push commandThe image was built or pulled under a different nameFix
    2. 2You push to a private or cloud registry, for example registry.example.com:5000/team/app, but the local image has no host in its nameThe registry host is missing from the local nameFix
    3. 3You typed docker push myuser/app and the image only exists as myuser/app:1.0No tag was given, so Docker pushed latestFix

What does the error look like?

  • tag does not exist: <name>:<tag>
  • An image does not exist locally with the tag: <name>

Cause 1 of 3

The image was built or pulled under a different name

1Check

Pushing does not rename anything. A build with -t app:dev creates app:dev only. Pushing myuser/app:1.0 needs an image with that name.

docker image ls --filter reference='myuser/*'

2Fix

Add the missing name to the existing image with docker tag, then push that name. The source can be a name or an image ID.

docker tag app:dev myuser/app:1.0
docker push myuser/app:1.0

3Verify

The push starts uploading layers and ends with a digest line.

docker image ls myuser/app

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The registry host is missing from the local name

1Check

Docker decides where to push from the host part of the name. Without it, the name means Docker Hub. Giving the registry only at push time does not link it to a locally tagged image.

docker image ls | grep app

2Fix

Tag the image with host, optional port, namespace and repository, then push that full name.

docker tag app:dev registry.example.com:5000/team/app:1.0
docker push registry.example.com:5000/team/app:1.0

3Verify

docker image ls lists the full registry name, and the push finishes.

docker image ls registry.example.com:5000/team/app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

No tag was given, so Docker pushed latest

1Check

A name without a tag means latest. The CLI adds it for you and prints a line starting with 'Using default tag'. If no image named latest exists locally, the push fails.

docker image ls myuser/app

2Fix

Push the tag you actually have, or create the latest tag from it.

docker push myuser/app:1.0
# or
docker tag myuser/app:1.0 myuser/app:latest
docker push myuser/app:latest

3Verify

The push completes for the tag you named.

docker image ls myuser/app

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Build with the final name in the first place: docker build -t registry.example.com:5000/team/app:1.0 .
  • In CI, store the full image name in one variable and use it for build, tag and push.
  • Always write the tag in push commands, so you never depend on the latest default.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.