Troubleshooting Common Issues

1. Resolving Port Already in Use

Issue	Solution	Notes
Port already in use	`docker ps -a docker stop <container_id> docker rm <container_id>`	Identify and remove conflicting containers
Port binding conflict	`docker port <container_id>`	Check which ports are bound to containers
Use different port	`docker run -p 8080:80 <image>`	Map container port to a different host port

Example: Stop and Remove Conflicting Container

docker ps -a
# Output:
# CONTAINER ID   IMAGE         COMMAND       CREATED        STATUS       PORTS       NAMES
# abc123         nginx         "nginx"       2 hours ago    Up 2 hours   80/tcp      nginx-container

docker stop abc123
docker rm abc123

Example: Map Different Host Port

docker run -p 8080:80 nginx

2. Fixing Volume Permission Errors

Issue	Solution	Notes
Permission denied when accessing volume	`chmod 755 /host/path`	Ensure host directory has appropriate permissions for container user
Container runs as different user	`chown -R 1000:1000 /host/path`	Match container user ID with host directory ownership
SELinux enabled	`chcon -Rt svirt_sandbox_file_t /host/path`	Use SELinux context to allow container access

Example: Fixing Volume Permissions

mkdir -p /home/user/data
chmod 755 /home/user/data
chown 1000:1000 /home/user/data

docker run -v /home/user/data:/app/data myapp

Note: Always verify directory permissions before mounting to avoid runtime errors.

Warning: Changing ownership of system directories can cause security issues.

3. Handling Out of Disk Space

Issue	Solution	Notes
Disk space exhausted	Run `docker system prune` to remove unused containers, networks, images, and build cache.	Use `-a` flag to remove all unused images, not just dangling ones.
Docker daemon logs consuming space	Check and rotate Docker logs using `journalctl --vacuum-size=100M` or configure log rotation in `/etc/docker/daemon.json`.	Log rotation prevents logs from growing indefinitely.
Large container layers or images	Use `docker image prune -a` to remove all unused images and `docker builder prune` to clean up build cache.	Pruning helps reclaim space from old or unused images.

Example: Pruning Docker Resources

docker system prune -a

Example: Configuring Log Rotation

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Note: Before running docker system prune, ensure no important containers or images are running or needed, as this action is irreversible.

4. Resolving Network Connectivity Issues

Issue	Cause	Solution
Containers cannot reach external services	Incorrect DNS configuration or firewall rules blocking traffic	Check `docker inspect <container>` for DNS settings. Ensure host firewall allows outbound traffic.
Containers cannot communicate with each other	Network mode mismatch or custom network not configured properly	Verify containers are on the same network using `docker network inspect <network>`. Use `--network` flag when running containers.
Port mapping fails to expose service	Incorrect port binding or host port already in use	Use `docker port <container>` to verify port mappings. Ensure host ports are available and use `-p <host_port>:<container_port>` correctly.

Example: Inspecting Container Network Configuration

docker inspect my-container | grep -A 5 "Networks"

Example: Mapping Ports Correctly

docker run -d --name web-server \
  -p 8080:80 \
  nginx

Note: When using custom networks, ensure that containers are attached to the same network and that the network allows inter-container communication.

5. Fixing Container Startup Failures

Issue	Symptoms	Diagnosis	Solution
Entrypoint/Command Failure	Container exits immediately with error	Check logs using `docker logs <container>`	Verify command exists in container or fix entrypoint
Port Conflicts	Container starts but can't bind to port	Use `docker port <container>` to check	Stop conflicting container or change port mapping
Resource Limits	Container fails to start or gets killed	Check `docker inspect <container>` for limits	Increase memory/cpu limits or reduce usage
Volume Mount Issues	Mount fails or container exits with permission error	Validate volume paths and permissions in host	Ensure directory exists and has proper access rights
Network Configuration	Container can't connect to network or services	Use `docker network ls` and inspect container networks	Recreate network or adjust container network mode

Example: Debugging Startup Failures

docker run -d --name debug-container nginx
docker logs debug-container
docker inspect debug-container

Note: Use docker events --filter container=<name> to monitor real-time container lifecycle events.

Warning: Avoid using --rm flag when debugging startup issues as container is removed immediately after exit.

6. Handling Build Context Too Large

Issue	Description	Solution
Build context size exceeds limits	Docker build fails when the build context is too large, typically due to including unnecessary files or directories.	Use a `.dockerignore` file to exclude unnecessary files from the build context.

Example: Using .dockerignore to reduce build context

# .dockerignore
node_modules
.git
*.log
.env
.DS_Store

Note: The .dockerignore file works similarly to .gitignore, excluding files and directories from the build context.

Workflow to reduce build context size

Create a .dockerignore file in the project root.
Add patterns to exclude large or unnecessary files (e.g., node_modules, .git, logs).
Rebuild the Docker image to verify reduced context size.

7. Resolving Image Pull Failures

Issue	Solution	Notes
docker pull `image:tag` fails with `unauthorized`	Run `docker login` or provide credentials via `--username` and `--password`	Common for private registries or Docker Hub with rate limits
docker pull `image:tag` fails with `manifest unknown`	Verify image name and tag exist; use `docker search` to confirm availability	Typically due to typo in image name or outdated tag
docker pull `image:tag` fails with `network error`	Check internet connectivity; retry after network recovery or use a mirror	May be caused by firewall, proxy, or registry downtime
docker pull `image:tag` times out or hangs	Adjust Docker daemon settings (e.g., `registry-mirrors`) or increase timeout limits	Can occur with large images or slow network connections

Example: Logging into Docker Hub

docker login

Example: Pulling an Image with Credentials

docker pull --username &lt;user&gt; --password &lt;pass&gt; registry.example.com/myapp:latest

Note: If you're using a private registry, ensure it's correctly configured in ~/.docker/config.json.

Warning: Avoid hardcoding credentials in scripts or command-line arguments. Use environment variables or credential helpers instead.

8. Fixing DNS Resolution Problems

Problem	Solution	Notes
Container cannot resolve external domains	Use `--add-host` or `--network` with custom DNS	May be due to Docker's default DNS server issues
Internal container names not resolving	Ensure containers are on the same network and use `--network`	Use `docker network inspect` to verify

Example: Using custom DNS server

docker run --dns 8.8.8.8 --dns 8.8.4.4 myapp

Example: Adding host entry

docker run --add-host=example.com:192.168.1.100 myapp

Note: If using Docker Desktop on Windows or macOS, DNS issues can stem from the host's network configuration.

Warning: Using --add-host is not persistent across container restarts.

9. Handling Container Memory Issues

Issue	Solution	Notes
Out of Memory (OOM) Errors	Use `--memory` flag to limit container memory usage.	Prevents containers from consuming all host RAM.
Memory Limits Exceeded	Set `--memory-swap` to allow swap usage.	Allows containers to use swap space when RAM is full.
High Memory Usage	Use `docker stats` to monitor container memory usage.	Identifies containers consuming excessive memory.

Example: Setting Memory Limits

docker run --memory=512m my-app

Example: Using Memory Swap

docker run --memory=1g --memory-swap=2g my-app

Note: Memory limits are enforced at the OS level and can cause containers to be killed if exceeded.

10. Resolving Docker Daemon Errors

Error Message	Possible Cause	Solution
Cannot connect to the Docker daemon	Daemon not running or inaccessible	`sudo systemctl start docker sudo usermod -aG docker $USER`
Permission denied	User not in docker group	`sudo usermod -aG docker $USER newgrp docker`
docker: Cannot connect to the Docker daemon	Docker service is stopped or crashed	`sudo systemctl restart docker`
Error while loading shared libraries: libdevmapper.so.1.02	Outdated or corrupted Docker installation	`sudo apt-get update sudo apt-get install --reinstall docker-ce`
dockerd: error while loading shared libraries	Missing or incompatible system libraries	`sudo ldconfig sudo apt-get install libdevmapper1.02.1`

Note: Ensure Docker is installed with the correct version compatible with your OS.

Example: Restarting Docker Service

sudo systemctl stop docker
sudo systemctl start docker

11. Fixing Registry Authentication Errors

Error Message	Cause	Solution
unauthorized: authentication required	Missing or invalid credentials for private registry	Run `docker login <registry-url>` with valid credentials
401 Unauthorized	Token expired or invalid	Re-authenticate using `docker login` or refresh token
no basic auth credentials	No credentials provided for registry access	Ensure `~/.docker/config.json` contains correct credentials

Example: Logging into a Private Registry

docker login https://my-private-registry.com
Username: myuser
Password: <secret>

Note: For registries like AWS ECR, use aws ecr get-login-password to fetch the password.

Warning: Avoid hardcoding credentials in scripts or Dockerfiles. Use environment variables or credential helpers.

Common Authentication Flow

Verify registry URL and access permissions
Run docker login with correct credentials
Check ~/.docker/config.json for stored credentials
If using CI/CD, ensure secrets are properly injected

12. Handling Compose File Errors

Error Type	Description	Solution
yaml.parser.error	Invalid YAML syntax in docker-compose.yml	Validate YAML structure using a linter or online validator. Ensure proper indentation and no trailing spaces.
version.mismatch	Unsupported or missing version field in compose file	Add or update the `version` field to a supported version like `'3.8'`.
service.not.found	Referenced service does not exist in the compose file	Check spelling and ensure all services are defined before referencing them.
network.not.found	Network referenced in service does not exist	Create the network explicitly or remove the reference if it's unnecessary.
volume.mount.error	Mounting volume fails due to incorrect path or permissions	Verify the host directory exists and has correct read/write permissions.

Example: Fixing Invalid YAML

# Incorrect YAML
services:
  web:
    image: nginx
    ports:
      - "8080:80"
  db:
    image: mysql
    environment:
      MYSQL_ROOT_PASSWORD: password

# Corrected YAML
services:
  web:
    image: nginx
    ports:
      - "8080:80"
  db:
    image: mysql
    environment:
      MYSQL_ROOT_PASSWORD: password

Note: Use docker-compose config to validate your compose file before running it.

Warning: Never commit sensitive data like passwords directly into the compose file. Use environment files or secrets instead.