24 Essential Docker Troubleshooting Tips to Fix Common Container Issues

1 Docker Migration of Storage Directory

Problem: /var/lib/docker directory grew too large, cannot delete directly.

Cause: Monitoring showed the Docker directory consuming excessive space.

Solution 1: Add a soft link after moving the directory.

# Stop Docker service
sudo systemctl stop docker
# Move directory
sudo mv /var/lib/docker /data/
# Create soft link
sudo ln -s /data/docker /var/lib/docker
# Start Docker service
sudo systemctl start docker

Solution 2: Modify Docker daemon configuration.

# Edit /lib/systemd/system/docker.service
ExecStart=/usr/bin/dockerd --graph=/data/docker/

{
  "live-restore": true,
  "graph": ["/data/docker/"]
}

Note: Use mv or cp with proper permissions when moving files.

2 Docker Device Space Insufficient

Problem: Container fails to start due to lack of disk space.

Check physical disk usage with df -Th and Docker info.

Solution: Clean unused data (logs) and enlarge Docker storage.

# Show largest container log files
du -d1 -h /var/lib/docker/containers | sort -h
# Truncate log file
cat /dev/null > /var/lib/docker/containers/<container_id>/container_log_name

Alternative: Increase base size in daemon config.

{
  "storage-opt": ["dm.basesize=20G"]
}

3 Docker Missing Shared Library

Problem: docker‑compose reports missing libz.so.1 .

Solution: Remount /tmp with exec permission.

sudo mount /tmp -o remount,exec

4 Docker Container File Corruption

Problem: Container cannot be stopped or removed.

Solution: Stop Docker, delete container files, run metadata checks, restart Docker.

# Stop Docker
sudo systemctl stop docker
# Remove container files
sudo rm -rf /var/lib/docker/containers
# Check and clear metadata
sudo thin_check /var/lib/docker/devicemapper/devicemapper/metadata
sudo thin_check --clear-needs-check-flag /var/lib/docker/devicemapper/devicemapper/metadata
# Start Docker
sudo systemctl start docker

5 Docker Graceful Restart

Problem: Restarting Docker daemon stops running containers.

Enable live‑restore in daemon config (Docker‑ce 1.12+).

{
  "live-restore": true
}

6 Docker Container Deletion Failure

Problem: Container cannot be removed; process not found.

Delete container directory manually and restart Docker.

# Remove container files
sudo rm -rf /var/lib/docker/containers/<container_id>
# Restart Docker
sudo systemctl restart docker.service

7 Docker MySQL Chinese Character Issue

Problem: MySQL inside Docker cannot display Chinese characters.

Set container locale to C.UTF-8.

# Temporary fix
docker exec -it <container> env LANG=C.UTF-8 /bin/bash
# Permanent fix in Docker run
docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

8 Docker Container Network Communication

Problem: Nginx container cannot reach backend service (502 error).

Replace localhost with host IP (e.g., 172.17.0.1) in nginx.conf.

When using host network mode, localhost refers to the host.

9 Docker Bus Error

Problem: Bus error occurs inside container.

Increase shared memory size with --shm-size (e.g., --shm-size=200m) or in docker‑compose.yml set shm_size: '2gb'.

Also ensure sufficient disk space.

10 Docker NFS Mount Error

Problem: File lock fails on NFS‑mounted volume.

Kernel version < 2.6.12 does not support flock over NFS. Upgrade kernel to >= 2.6.12.

11 Docker Default Subnet Conflict

Problem: Services cannot communicate due to overlapping Docker subnet.

Manually set Docker default address pools in /etc/docker/daemon.json.

{
  "default-address-pools": [{"base":"172.17.0.0/12","size":24}]
}

12 Docker Compose Project Label Conflict

Problem: Two compose projects interfere because they share the same label com.docker.compose.project .

Rename project directories or use -p flag to set distinct project names.

13 Docker Exec TTY Issue in CI

Problem: docker exec -it fails in CI because no TTY is allocated.

Remove -t (or -i) when running non‑interactive CI jobs.

14 Docker Cron Job Failure

Problem: MySQL backup via Docker in crontab results in empty dump.

Crontab is non‑interactive; remove -i (or -t) from docker exec command.

15 Docker Compose Environment Variable Quoting

Problem: Variables with quotes are not recognized.

Do not quote values in docker‑compose.yml or .env files.

16 Docker Image Deletion Conflict

Problem: Cannot delete image because child images depend on it.

Identify dependent images with

docker image inspect --format '{{.RepoTags}} {{.Id}} {{.Parent}}' $(docker image ls -q --filter since=<image_id>)

and delete by tag.

17 Docker Nginx Permission Error

Problem: Nginx cannot write to log or cache directories when running as non‑root.

Adjust nginx.conf paths to directories with proper permissions (e.g., /data/logs, /dev/shm).

18 Docker IPv6 Binding Issue

Problem: Docker tries to bind ports on IPv6, but the host disables IPv6.

Either bind explicitly to IPv4 (e.g., "0.0.0.0:80:80/tcp") in docker‑compose.yml or disable IPv6 in Docker daemon config:

{
  "ipv6": false,
  "fixed-cidr-v6": "2001:db8:1::/64"
}

19 Docker Container Startup Timeout

Problem: docker‑compose up times out after ~2 minutes.

Increase timeout variables: export COMPOSE_HTTP_TIMEOUT=500 and export DOCKER_CLIENT_TIMEOUT=500.

20 Docker Port Access Blocked by Firewall

Problem: Nginx returns 502 because backend ports are blocked.

Open required ports with firewall-cmd --add-port=8080/tcp (and others) or stop the firewall.

21 Docker Image Not Found

Problem: Pulling private image fails with “manifest unknown”.

Check image tag spelling; the correct tag was 0.0.10 not 0.10.

22 Keep Docker‑Compose Container Running

Problem: Service restarts endlessly due to failure.

Use a hanging command such as tail -f /dev/null via command or entrypoint and set tty: true in compose.

23 Avoid Default Docker Subnet Overlap

Problem: Default Docker subnet conflicts with internal network.

Configure custom address pool in /etc/docker/daemon.json (e.g., "base":"192.168.100.0/20","size":24) and restart Docker.

24 Add Private Docker Registry

Problem: Pulling from private registry fails with TLS error.

Add registry to insecure registries list:

{
  "insecure-registries": ["192.168.31.191:5000"]
}

Restart Docker and login.