Top 17 Docker Troubleshooting Tips: From Storage Migration to Network Errors

Docker storage directory migration

Docker stores container data under /var/lib/docker by default. To move this directory to a larger volume:

Stop the Docker daemon: sudo systemctl stop docker Move the directory (preserving permissions): sudo mv /var/lib/docker /data/docker Optionally create a symlink if the original path must remain: sudo ln -s /data/docker /var/lib/docker Restart Docker: sudo systemctl start docker Alternatively, set a new graph path in /etc/docker/daemon.json or the service file:

{
  "graph": "/data/docker"
}

Docker device space shortage

When the host filesystem is full, containers cannot start. Diagnose with:

# Show filesystem usage
df -Th
# Show Docker storage driver info
docker info

Common remedies:

Delete or truncate large log files:

# Find biggest log files
du -d1 -h /var/lib/docker/containers | sort -h
# Truncate a specific log
cat /dev/null > /var/lib/docker/containers/CONTAINER_ID/CONTAINER_LOG

Increase the default devicemapper base size (default 10 GB):

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

If the error is caused by inode exhaustion, check inode usage with df -i and remount the filesystem with the inode64 option.

Missing shared library libz.so.1

Docker‑compose may fail with error while loading shared libraries: libz.so.1 because the /tmp mount lacks execution permission. Fix by remounting:

sudo mount /tmp -o remount,exec

Corrupted Docker container files

If a container becomes unmanageable, clean its metadata:

Stop Docker: sudo systemctl stop docker Remove the container's directory (replace CONTAINER_ID with the actual ID):

sudo rm -rf /var/lib/docker/containers/CONTAINER_ID

Check and clear devicemapper 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 again:

sudo systemctl start docker

Graceful container restart (live‑restore)

Enable live-restore so containers keep running when the daemon stops:

{
  "live-restore": true
}

Reload the daemon configuration:

sudo systemctl reload docker

Unable to delete a Docker container

If docker rm -f CONTAINER_ID fails with a conflict error, manually delete the container's directory and restart Docker:

sudo rm -rf /var/lib/docker/containers/CONTAINER_ID
sudo systemctl restart docker

MySQL container Chinese characters

The default POSIX locale does not support Chinese. Set a UTF‑8 locale when running the container:

# Temporary fix
docker exec -it CONTAINER_ID env LANG=C.UTF-8 /bin/bash
# Permanent fix (run)
docker run --name mysql-utf8 -e MYSQL_ROOT_PASSWORD=secret -d \
  -e LANG=C.UTF-8 mysql:latest \
  --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

Container network connectivity (Nginx proxy)

Inside a container, localhost refers to the container itself. Use the host's bridge IP (e.g., 172.17.0.1) or the host network mode.

# Find host bridge IP
ip addr show docker0
# Example nginx.conf snippet
proxy_pass http://172.17.0.1:8080;

Bus error inside container

A bus error often indicates insufficient shared memory. Launch the container with a larger --shm-size (default is 64 MiB):

docker run -it --rm --shm-size=200m pytorch/pytorch:latest

Also ensure enough free disk space.

NFS mount file‑locking error

Older kernels (< 2.6.12) do not support flock() over NFS. Upgrade to a kernel version that includes the fix (e.g., 3.10.0-693.18.1.el7) to enable proper file locking on NFSv3/v4.

Docker default address pool conflict

Conflicting subnets can arise when Docker automatically selects address pools. Define a stable pool in /etc/docker/daemon.json:

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

Docker‑compose project label clash

Compose uses the directory name as the com.docker.compose.project label. Identical project names cause containers from different compose files to interfere. Resolve by:

Renaming the project directories, or

Providing an explicit project name with -p:

docker-compose -f docker-compose.yml -p app1 up -d

Docker exec fails in CI (no TTY)

CI pipelines lack a TTY, so the -t flag causes an error. Remove -t (and -i if not needed) when running commands in CI.

Cron‑based Docker command issues

Cron jobs are non‑interactive. Using both -i and -t with docker exec yields empty output. Omit -i and keep -t only if a pseudo‑TTY is required.

Compose environment variable quoting

YAML parsing treats quoted strings as literal values, which can break variable substitution. Define variables without surrounding quotes:

# Correct
TESTVAR=test
# Incorrect (fails)
TESTVAR="test"

Unable to delete an image with dependent child images

An image referenced by other images cannot be removed directly. Identify dependent images and delete them first, or remove dangling images:

# List dependent tags
docker image inspect --format='{{.RepoTags}} {{.Id}} {{.Parent}}' $(docker image ls -q --filter since=IMAGE_ID)
# Remove dangling images
docker rmi $(docker images --filter "dangling=true" -q)

Running Docker as a non‑root user

When services run under a non‑root user, file‑system permissions must be adjusted. Example Nginx configuration that writes logs and temporary files to writable paths:

user  www-data;
error_log  /data/logs/master_error.log warn;
pid        /dev/shm/nginx.pid;
client_body_temp_path  /tmp/client_body;
fastcgi_temp_path     /tmp/fastcgi_temp;
proxy_temp_path       /tmp/proxy_temp;

Ensure the directories exist and are owned by the non‑root user.