Introduction

This Docker error usually appears when you try to remove an image or tag that is still referenced somewhere else. The fix is not random cleanup; it is identifying what still points at that image and removing those references in the right order.

What the Error Actually Means

Docker keeps track of images, tags, and containers separately. A repository reference is usually a tag such as my-app:latest, while the underlying image may also be tagged with another name or used by one or more stopped containers.

A typical failure looks like this:

docker rmi my-app:latest

Error response from daemon: conflict: unable to remove repository reference "my-app:latest"

Docker is telling you that deleting that reference would leave another active dependency in an invalid state.

Step 1: Check for Containers Using the Image

The most common cause is a running or stopped container created from the image. List them first:

docker ps -a --filter ancestor=my-app:latest

If Docker returns containers, remove them before removing the image:

docker stop container_id
docker rm container_id
docker rmi my-app:latest

If you want a single command for cleanup during local development, use:

docker rm -f container_id

Be careful with force removal in shared environments because it stops the container immediately.

Step 2: Check Whether the Image Has Multiple Tags

An image can have more than one repository reference. Removing one tag does not necessarily remove the image itself, and Docker may complain if you expect docker rmi to erase everything in one step.

Inspect the image references:

docker image ls --digests

You may see output where two tags point to the same image ID:

REPOSITORY   TAG       IMAGE ID
my-app       latest    abc123def456
my-app       debug     abc123def456

In that case, remove the tags one by one:

docker rmi my-app:latest
docker rmi my-app:debug

Only after the last tag is removed can Docker delete the unreferenced image data.

Step 3: Remove by Image ID When Appropriate

Sometimes it is clearer to work with the image ID directly, especially when tags are confusing or duplicated across local builds.

docker image ls
docker image rm abc123def456

If the image is still used by a container, Docker will still block deletion. That is useful because it prevents accidental removal of an image your environment depends on.

Step 4: Clean Up Dangling Resources

If you have many abandoned test runs, dangling images and stopped containers can clutter the local Docker state. Prune commands help, but they should be used intentionally.

docker container prune
docker image prune

For a broader cleanup:

docker system prune

This removes stopped containers, unused networks, and dangling images. It is helpful on a development laptop, but it can remove resources you expected to reuse.

A Safe Troubleshooting Sequence

When you want a predictable workflow, use the same checklist every time:

1docker ps -a --filter ancestor=my-app:latest
2docker image ls
3docker image inspect my-app:latest
4docker rmi my-app:latest

If the remove still fails, inspect the matching containers and tags rather than jumping straight to -f. The conflict message is usually accurate enough to guide the next step.

Common Pitfalls

One common mistake is assuming the problem is the container named in your terminal history. The real blocker may be a different stopped container created days earlier. Always check docker ps -a, not just running containers.

Another mistake is confusing tag removal with image removal. Deleting my-app:latest may only remove one label from the image. If my-app:test still points to the same image ID, the image remains.

Force removal is also overused. docker rmi -f can solve a local mess, but it skips the habit of understanding the dependency chain. That makes repeated problems more likely.

Finally, users often prune too aggressively. Cleanup commands are useful, but they should come after inspection, not before it, so you know what was actually holding the reference.

Summary

• This conflict means Docker still sees a valid reference to the image or tag you are trying to remove.
• Check for running and stopped containers with docker ps -a --filter ancestor=....
• Inspect whether multiple tags point to the same image ID before assuming removal failed.
• Remove containers first, then tags, then the image itself if needed.
• Use prune commands for cleanup, but only after you understand what Docker is protecting.