Docker Troubleshooting Guide: Storage Migration, Network Issues, and Common Pitfalls

1 Docker storage migration

By default Docker stores data in /var/lib/docker. When the directory grows too large you can move it to another location.

Problem : Disk usage of /var/lib/docker is high.

Solution 1 – symlink

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

Solution 2 – edit daemon config

# Edit service file
sudo vim /lib/systemd/system/docker.service
ExecStart=/usr/bin/dockerd --graph=/data/docker/
# Or edit daemon.json
sudo vim /etc/docker/daemon.json
{
  "graph": "/data/docker/"
}

Notes : Avoid using symlinks with orchestration tools like Kubernetes.

2 Docker device space shortage

When containers cannot start because the host disk is full, check the physical disk usage and Docker’s storage driver.

# Check host disk
$ df -Th
# Check Docker info
$ docker info

Common fixes:

Clean up unused images and logs.

Resize the Docker data directory via --graph or daemon.json settings.

Increase --shm-size for containers that need more shared memory.

3 Missing shared libraries

Docker Compose may fail with libz.so.1 errors. The fix is to remount /tmp with exec permissions:

# Remount /tmp
sudo mount /tmp -o remount,exec

4 Container file corruption

If a container becomes unresponsive, stop Docker, remove the container files under /var/lib/docker/containers, and restart Docker.

# Stop Docker
sudo systemctl stop docker
# Remove corrupted container files
sudo rm -rf /var/lib/docker/containers/<container_id>
# Start Docker
sudo systemctl start docker

5 Container cannot start due to unhealthy state

Adjust the Docker daemon to increase the default container size (e.g., dm.basesize=20G) in /etc/docker/daemon.json or the service file, then reload and restart Docker.

{
  "live-restore": true,
  "storage-opt": ["dm.basesize=20G"]
}

6 Nginx proxy to host services

When Nginx runs inside a container, using localhost in proxy_pass points to the container itself. Replace it with the host IP (e.g., 172.17.0.1) or use --network=host.

# Example proxy_pass
proxy_pass http://172.17.0.1:8080;

7 Docker network default subnets

Docker may allocate different private subnets (e.g., 172.17.0.0/12 or 192.168.0.0/16) causing inter‑container communication issues. Manually set the desired subnet in /etc/docker/daemon.json:

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

8 Docker‑compose project label conflict

Compose uses the label com.docker.compose.project derived from the directory name. If two projects share the same directory name, containers may be restarted unintentionally. Use distinct directory structures or the -p flag to set a unique project name.

# Specify project name
docker-compose -f ./docker-compose.yml -p app1 up -d

9 Docker exec tty/interactive flags

Running docker exec -it in non‑interactive environments (CI, cron) fails because no TTY is allocated. Remove -t for CI scripts or keep -i only when STDIN is needed.

# CI safe command
docker exec -i <container> your_command

10 Cron jobs with Docker exec

Cron runs without a TTY; using -it causes failures. Use only -i or omit both flags for background tasks.

# Cron example
0 */6 * * * docker exec -i <container> sh -c 'mysqldump ...'

11 Environment variable quoting in Compose

YAML parsing adds extra quotes. Define variables without quotes to avoid unexpected values.

# Correct
TEST_VAR=test
# Incorrect (adds extra quotes)
TEST_VAR="test"

12 Removing images with dependent children

Docker refuses to delete an image that has child images. List dependent images and delete them first, or remove by tag.

# List dependent images
docker image inspect --format '{{.RepoTags}} {{.Id}} {{.Parent}}' $(docker image ls -q --filter since=<image_id>)
# Remove by tag
docker rmi -f <tag>
# Remove dangling images
docker rmi $(docker images -f "dangling=true" -q)

13 Switching container user

Running services as root inside containers can cause permission errors. Set the appropriate user in the service configuration (e.g., user www-data; for Nginx) and ensure file permissions match.

user  www-data;
error_log  /data/logs/master_error.log warn;

14 IPv6 binding issue

If the host disables IPv6, Docker may try to bind ports on tcp6 and fail. Either enable IPv6 on the host or force Docker to bind only on IPv4 by specifying the address in docker‑compose.yml or disabling IPv6 in /etc/docker/daemon.json:

{
  "ipv6": false
}

15 Docker compose HTTP timeout

Long‑running compose operations can hit the default 60‑second HTTP timeout. Increase the timeout via environment variables:

export COMPOSE_HTTP_TIMEOUT=500
export DOCKER_CLIENT_TIMEOUT=500

16 I/O bottleneck during container start

Heavy volume mounts can cause slow container startup. Identify high I/O processes (e.g., rg from VS Code) and stop them, or reduce the amount of data mounted.

17 Firewall blocking container ports

When Nginx proxies to backend containers, a No route to host error often means the firewall blocks the target ports. Open the required ports or disable the firewall.

# Open ports
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=8081/tcp
sudo firewall-cmd --reload

18 Private registry access

Pulling from a private registry without configuring it as insecure results in x509: certificate signed by unknown authority. Add the registry to insecure-registries and restart Docker.

{
  "insecure-registries": ["192.168.31.191:5000"]
}
sudo systemctl restart docker

19 Keeping a container alive for debugging

Use tail -f /dev/null as the container’s command or entrypoint to prevent it from exiting while you investigate issues.

# docker‑run example
docker run -it --rm --entrypoint=/bin/bash myimage
# docker‑compose example
command: tail -f /dev/null

20 Avoiding default Docker subnet conflicts

If your internal network overlaps Docker’s default subnet, define a non‑overlapping pool in /etc/docker/daemon.json and restart Docker.

{
  "default-address-pools": [{
    "base": "10.210.200.0/24",
    "size": 28
  }]
}
sudo systemctl restart docker

21 Image tag typo

Docker reports manifest unknown when the image tag is misspelled (e.g., 0.10 instead of 0.0.10). Verify the exact tag name.

22 Using Docker without default network

Configure a custom address pool to prevent Docker from allocating overlapping subnets.

{
  "default-address-pools": [{
    "base": "192.168.100.0/20",
    "size": 24
  }]
}