Skip to main content

Docker Troubleshooting

Many Docker problems look different on the surface, but the troubleshooting approach can be fairly consistent. Rather than reinstalling at the first sign of trouble, I recommend quickly going through "service status, logs, configuration, ports, mounts" first.

Minimal Troubleshooting Sequence​

I typically follow this order:

  1. docker ps -a
  2. docker logs <container>
  3. docker inspect <container>
  4. docker info
  5. sudo systemctl status docker
  6. sudo journalctl -u docker.service -n 100 --no-pager

1. docker pull Is Slow, Times Out, or Fails​

First determine whether Docker itself is down or whether the issue is with the connection to the image registry.

Check These First​

docker info
docker pull ubuntu:22.04

Focus on:

  • Whether the Docker daemon is running normally
  • Whether an image accelerator is configured
  • Whether small images can be pulled successfully

If you are on an Alibaba Cloud machine and the main issue is slow Docker Hub access, you can check this existing record:

Two additional habits I follow:

  • Try to pin image tags rather than relying on latest
  • Pull commonly used base images locally in advance or sync them to your own registry

2. Permission Denied When Accessing Docker​

The typical error usually looks like this:

permission denied while trying to connect to the Docker daemon socket

First confirm the daemon is running:

sudo systemctl status docker

If Docker is running but the current user lacks permissions, add the user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Then log in again and try:

docker ps

Note: docker group permissions are not low. On shared machines or production servers, think carefully about whether everyone should have this permission.

3. Host Port Already in Use​

If a container reports a port conflict at startup, first confirm who is actually using the port:

ss -lntp | grep 8080
docker ps --format "table {{.Names}}\t{{.Ports}}"

Common solutions:

  • Change the host port, e.g., change 8080:80 to 18080:80
  • Stop the conflicting service
  • If it's only for local access, explicitly bind to 127.0.0.1

For a more systematic explanation, see:

4. Container Exits Immediately After Starting​

For this type of problem, don't focus on the docker run command itself first. Check the container status and logs:

docker ps -a
docker logs my-container
docker inspect --format '{{.State.ExitCode}}' my-container

The most common causes are:

  • The main process exited after completing
  • The startup command is wrong
  • Application configuration is missing
  • Dependent ports, files, or databases are unreachable

If you suspect an issue with the image's internal environment, temporarily enter the container:

docker run --rm -it my-image:latest sh

5. Files Are Wrong After Mounting, or Data Disappeared Mysteriously​

First distinguish which type you are actually using:

  • bind mount
  • named volume
  • Container writable layer

Then check the container's actual mount situation:

docker inspect my-container

High-frequency issues are usually:

  • The host path does not exist
  • Mounting a file as a directory, or a directory as a file
  • A bind mount hiding the original directory content from the image
  • The container process user lacks read/write permissions

If you are torn between "should I use a volume or a bind mount," go directly to:

6. Don't Know What's Actually Happening​

Don't rush to guess. First, get the full picture of the current state:

docker ps -a
docker logs -f --tail 100 my-container
docker inspect my-container
docker stats

If you still have no direction, check the Docker service itself:

sudo systemctl status docker
sudo journalctl -u docker.service -n 100 --no-pager

7. Commands Work Inside the Container but Host Can't Access​

Check these three things first:

  1. Is the application listening on 0.0.0.0 inside the container?
  2. Was -p included when starting the container?
  3. Is the host or cloud platform blocking the port?

Helper commands:

docker port my-container
ss -lntp | grep 8080

My Minimal Decision Principles​

  • Check status and logs first, don't reinstall first
  • Confirm whether the problem is with the container, the image, or the host
  • Check actual configuration, don't rely on memory
  • If you can reproduce it, document it. Don't let the same pitfall come back next time