🚨 Docker Error Guide: 'conflict: unable to remove repository reference' Image Removal Failures

Exact Error Message

conflict errors appear when docker rmi (or docker image rm) can’t remove an image because something still depends on it:

docker rmi app:latest

Error response from daemon: conflict: unable to remove repository
reference "app:latest" (must force) - container a1b2c3 is using its
referenced image 9f2e...

Error response from daemon: conflict: unable to delete 9f2e... (cannot
be forced) - image has dependent child images

Error response from daemon: conflict: unable to delete 9f2e... (must be
forced) - image is referenced in multiple repositories

The image and its data are intact; Docker is refusing a removal that would break something still pointing at it.

What the Error Means

Docker refuses to delete an image when removing it would orphan a dependency, and the message tells you which kind of dependency:

• “container … is using its referenced image (must force)” — a container (running or stopped) was created from this image. Removing the image would leave that container without its backing image, so Docker blocks it.
• “image has dependent child images (cannot be forced)” — another image was built FROM this one (or shares it as a parent layer). You literally cannot delete a parent while children depend on it.
• “image is referenced in multiple repositories / multiple tags (must be forced)” — the same image ID has several tags. docker rmi <id> would remove the underlying image that all those tags share, so Docker asks you to either untag specifically or force.

“Must force” means you can override with -f once you understand the consequence; “cannot be forced” means you must remove the dependent (the child image) first. Distinguishing the three is the whole job.

Common Causes

• A stopped container still references the image. docker ps looks clean, but docker ps -a reveals an exited container created from it.
• A running container is using the image right now.
• Child images depend on it. Local images built FROM this image hold it as a parent layer.
• Multiple tags share one image ID. You tagged the same build several times (app:latest, app:1.4, registry/app:1.4).
• Dangling intermediate images from old builds still reference shared layers.
• You removed by ID instead of by tag, so Docker sees an ID with multiple repository references.

How to Reproduce the Error

Create a container from an image, then try to remove the image:

docker pull alpine:3.20
docker create --name holder alpine:3.20
docker rmi alpine:3.20

Error response from daemon: conflict: unable to remove repository
reference "alpine:3.20" (must force) - container <id> is using its
referenced image ...

Clean up with docker rm holder && docker rmi alpine:3.20.

Diagnostic Commands

Find every container (running or stopped) that references the image:

docker ps -a --filter ancestor=app:latest
docker ps -a --format '{{.ID}}\t{{.Image}}\t{{.Status}}' | grep app

List all tags pointing at the same image ID (the “multiple repositories” case):

docker images --digests | grep app
docker image inspect app:latest --format '{{.Id}}: {{json .RepoTags}}'

Find child images that were built from this one:

docker image inspect app:latest --format '{{.Id}}'
docker images --filter since=app:latest

Read the daemon log for the precise conflict it reported:

journalctl -u docker --since "10 min ago" | grep -i 'conflict\|in use\|child\|reference'

Step-by-Step Resolution

Cause: a container references it. Remove the container(s) first, then the image — this is the safe path that doesn’t need -f:

docker ps -a --filter ancestor=app:latest
docker rm <container-id>          # add -f if it's running and you want it gone
docker rmi app:latest

docker rm -f stops and removes a running container; only do that if you’re sure the workload is disposable.

Cause: multiple tags on one ID. Don’t force-delete the shared ID. Remove the tag you no longer want; the image stays until its last tag is gone:

docker rmi app:1.4            # removes just this tag/reference
docker images | grep app      # other tags remain intact

Cause: dependent child images (cannot be forced). Remove the children first, working from the leaf images down to the parent:

docker images --filter since=app:latest
docker rmi <child-image>
docker rmi app:latest

Cause: dangling/unused images cluttering things. Prune what’s genuinely unreferenced:

docker image prune          # removes dangling images
docker image prune -a       # removes all images not used by a container

Forcing, with care. docker rmi -f app:latest overrides “must force” cases (container/tag references), but it leaves any referencing container pointing at a now-missing image, which can cause odd behavior. Prefer removing the dependent first; reserve -f for when you’ve confirmed the consequence.

A worked example. A cleanup script failed nightly with conflict: unable to remove repository reference "build:cache" (must force). docker ps showed nothing running, so it looked like a bug — but docker ps -a --filter ancestor=build:cache revealed dozens of exited job containers from the day’s CI runs, each still referencing the image. The fix was to remove the spent containers first (docker container prune -f) and only then docker rmi. The script was reordered to prune stopped containers before images, and the conflict never recurred.

Prevention and Best Practices

• Remove containers (or docker container prune) before removing the images they were created from.
• Untag images you no longer want by tag rather than force-deleting a shared image ID.
• Use docker image prune -a on a schedule to clear images no container references, instead of targeted force-removes.
• In CI, clean up job containers as part of the pipeline so they don’t accumulate references to base images.
• Check docker ps -a (not just docker ps) when an image “in use” error surprises you — stopped containers count.

Related Errors

• Docker Error Guide: ‘device or resource busy’ — the volume-removal equivalent of a “still in use” refusal.
• Docker Error Guide: ‘no space left on device’ — when removing images is part of reclaiming storage.
• See more Docker troubleshooting guides.

Frequently Asked Questions

docker ps is empty — why is the image “in use”? Stopped containers still reference their image. Check docker ps -a --filter ancestor=<image> and remove those exited containers first.

What’s the difference between “must force” and “cannot be forced”? “Must force” you can override with -f (container/tag references). “Cannot be forced” means a child image depends on it; you must delete the child first — -f won’t help.

Will force-removing delete my data? It removes the image reference. Containers created from it still exist (now pointing at a missing image) until you remove them. It’s cleaner to remove the container first.

Why does removing one tag not delete the image? When several tags share one image ID, removing a tag only drops that reference. The underlying image is deleted when its last tag/reference is gone.