How to fix Docker error cannot delete docker container conflict unable to remove repository reference?

This error comes when you try to delete/remove your docker image before removing your docker container. The basic principle of docker says you should always remove your docker container first before removing the docker image.

In this article, we are going to see how to fix this issue along with the recommended way to handle the removal/deletion of the docker container and docker images.

Now the question comes - What is the difference between Docker images and Docker container?

Answer - Docker container is a runnable instance of Docker image. So if draw the tree hierarchy of Docker image and Docker container then Docker Image will sit at the top and Docker Container will sit underneath. So if want to remove the Docker image then first you should need to remove the Docker Container and then the Docker image associated with the Docker container.

Let's break down all the steps and target each step to fix the issue -

Table content

1. Step 1 - List all the container
2. Step 2 - List all the images
3. Step 3 - Pick the container which you want to delete/remove
4. Step 4 - Remove the corresponding docker images associated with the docker container
5. Step 5 - If nothing works then use last resort use docker system prune

1. Step 1 - List all the container

Before we start troubleshooting the error the first step which we need is to check all the running container. Use the following docker command to check all the running container inside your machine -

1docker ps -a

This will list out all of your running containers as well exited containers -

1 CONTAINER ID        IMAGE                                COMMAND                CREATED             STATUS              PORTS                    NAMES
2794e4a93f514        jhooq-spring-boot-docker-compose:1   "java -jar /app.jar"   18 minutes ago      Up 18 minutes       0.0.0.0:8080->8080/tcp   hooq-k8s_jhooq-springboot-container_1

(Note: For the example purpose I am taking only one container jhooq-spring-boot-docker-compose)

2. Step 2 - List all the images

Alright now we know all the containers which are running, now we should check all the images associated with the docker container.

And the command for checking the images is -

1docker image ls 

The above command will list out all the docker images which are available and also associated with your docker container. Here is the following output which I got after running the docker image ls command

1REPOSITORY          TAG                     IMAGE ID       CREATED       SIZE
2jhooq-docker-demo   jhooq-docker-demo       8dab1cc236da   2 days ago    93.6MB

Since I have created this article with only one docker container and one docker image but in your case you might see more number of images once you run the command docker image ls

3. Step 3 - Pick the container which you want to delete/remove

Now you should pick the container name from Step 1 which you want to delete. For this guide, the container which I am running is jhooq-spring-boot-docker-compose with the container id 794e4a93f514.

To remove the container we are going to use the container id (Note : Please replace your container ID with your suitable container ID)-

1 docker rm 794e4a93f514

The above command will first stop the container with container id 794e4a93f514

4. Step 4 - Remove the corresponding docker images associated with the docker container

Okay so now we have deleted the docker container in step 3, lets delete/remove the docker images associated with the container.

(Note: Always make sure that you have stopped and removed the container before removing the image. Also in the following command please update your image id before running it.)

1docker rmi 8dab1cc236da 

If you can complete all the 4 steps in the same sequence then your error cannot delete docker container conflict unable to remove repository reference must be resolved now.

But if by any chance the above steps do not work for you and you are still stuck with the same issue then I would recommend you to use docker system prune which we are going to see in Step 5.

Step 5 - If nothing works then use last resort use docker system prune

If you come this far then I can guess you have tried all the 4 steps mentioned in this blog but you are still stuck with the issue.

There is one more command docker system prune which can help you to fix the issue but this command should be used as a last resort because if you use it without knowing it impact then your might lose a lot rather than fixing the issue.

The simplest way to use the command is -

1docker system prune -a  

It will delete/remove all the containers, network, unused images and build caches.

But we can customize the docker system prune command by supplying different parameters to it. Read this article - On how to use docker prune.

Here are some reference for further reading -

1. Stackoverflow - Docker error cannot delete docker container, conflict: unable to remove repository reference
2. GitHub - Docker rmi unable to remove images