docker-troubleshooting-knowledge

Docker Troubleshooting Knowledge Base

Quick reference for debugging Docker containers in PHP projects.

Common Build Errors

Error	Cause	Solution
failed to compute cache key	File not in build context	Check .dockerignore, verify file path
returned a non-zero code: 137	OOM during build	Increase Docker memory or reduce parallel ops
Could not find package	Composer can't resolve deps	Check composer.lock, mount auth secrets
E: Unable to locate package	Missing apt repository	Add required repo or use correct base image
configure: error: ... not found	Missing dev library	Install -dev package before ext install
Permission denied	Wrong user/permissions	Fix chown/chmod or adjust USER directive
COPY failed: file not found	File not in context	Check path relative to Dockerfile, check .dockerignore
max depth exceeded	Too many layers	Combine RUN commands, use multi-stage build

Common Runtime Errors

Error	Cause	Solution
502 Bad Gateway	PHP-FPM not running or crashed	Check FPM logs, verify listen address
Connection refused (port 9000)	FPM not listening	Check listen directive, container networking
OOM Killed	Memory limit exceeded	Increase limits, tune pm.max_children
No space left on device	Disk/overlay full	Prune images/volumes, increase disk
exec format error	Wrong platform image	Build for correct arch (linux/amd64)
name resolution failure	DNS issue	Check network config, service names
read-only file system	Read-only FS enabled	Mount tmpfs for writable dirs
file not found (FastCGI)	Wrong SCRIPT_FILENAME	Check nginx root and fastcgi params

Diagnostic Commands

Container Inspection

# View container logs (last 100 lines, follow)
docker logs --tail 100 -f <container>

# Execute command inside running container
docker exec -it <container> sh

# Inspect container configuration
docker inspect <container>

# Container resource usage (live)
docker stats <container>

# List processes inside container
docker top <container>

# View container events
docker events --filter container=<container>

# Check container health status
docker inspect --format='{{json .State.Health}}' <container> | jq

Image Inspection

# View image layers and sizes
docker history <image>

# Inspect image metadata
docker inspect <image>

# Check image size
docker images <image> --format '{{.Size}}'

# Export image filesystem for inspection
docker save <image> | tar -tvf -

Resource Diagnostics

# Disk usage summary
docker system df

# Detailed disk usage
docker system df -v

# Prune unused resources
docker system prune -a --volumes

# List dangling images
docker images -f "dangling=true"

PHP-FPM Debugging

Enable Slow Log

; www.conf
request_slowlog_timeout = 3s
slowlog = /dev/stderr

Enable Access Log with Timing

access.log = /dev/stdout
access.format = '{"time":"%T","method":"%m","uri":"%r","status":"%s","duration":"%d","memory":"%{mega}M"}'

Check FPM Status

# Enable status page in www.conf
# pm.status_path = /fpm-status

# Query FPM status
docker exec <container> sh -c \
    'SCRIPT_NAME=/fpm-status SCRIPT_FILENAME=/fpm-status REQUEST_METHOD=GET \
    cgi-fcgi -bind -connect 127.0.0.1:9000'

# Full status (per-process details)
docker exec <container> sh -c \
    'SCRIPT_NAME=/fpm-status SCRIPT_FILENAME=/fpm-status QUERY_STRING=full REQUEST_METHOD=GET \
    cgi-fcgi -bind -connect 127.0.0.1:9000'

Check PHP Configuration

# View loaded PHP modules
docker exec <container> php -m

# View PHP configuration
docker exec <container> php -i | grep -i opcache

# Check for configuration errors
docker exec <container> php -r "phpinfo();" | grep -i error

# Validate PHP syntax
docker exec <container> php -l /var/www/html/public/index.php

Network Debugging

DNS Resolution

# Check DNS from inside container
docker exec <container> nslookup postgres
docker exec <container> getent hosts postgres

# Check network connectivity
docker exec <container> ping -c 3 postgres

# Check port connectivity
docker exec <container> nc -zv postgres 5432

# List container networks
docker inspect <container> --format='{{json .NetworkSettings.Networks}}' | jq

Port Mapping

# Check port bindings
docker port <container>

# Check listening ports inside container
docker exec <container> netstat -tlnp
# or with ss
docker exec <container> ss -tlnp

Network Inspection

# List all networks
docker network ls

# Inspect network
docker network inspect <network>

# Check connected containers
docker network inspect <network> --format='{{json .Containers}}' | jq

Volume and Permission Debugging

Permission Issues

# Check file ownership inside container
docker exec <container> ls -la /var/www/html

# Check running user
docker exec <container> whoami
docker exec <container> id

# Fix permissions (temporary)
docker exec -u root <container> chown -R app:app /var/www/html

Volume Issues

# List volumes
docker volume ls

# Inspect volume
docker volume inspect <volume>

# Check volume mount points
docker inspect <container> --format='{{json .Mounts}}' | jq

# Verify volume contents
docker run --rm -v <volume>:/data alpine ls -la /data

Compose-Specific Debugging

# View all service statuses
docker compose ps

# View service logs (all services)
docker compose logs -f

# View specific service logs
docker compose logs -f php

# Validate compose file
docker compose config

# Recreate specific service
docker compose up -d --force-recreate php

# View service events
docker compose events

Quick Diagnosis Flowchart

Container not starting?
  |
  +-- Check: docker logs <container>
  |     |
  |     +-- Permission error --> Fix chown/chmod or USER
  |     +-- Config error --> Validate config files
  |     +-- OOM killed --> Increase memory limits
  |
  +-- Check: docker inspect <container> | grep State
        |
        +-- Restarting --> Check restart policy + logs
        +-- Exited --> Check exit code (137=OOM, 1=error)

502 Bad Gateway?
  |
  +-- Check: docker exec php ps aux (is FPM running?)
  |     |
  |     +-- Not running --> Check FPM config + logs
  |     +-- Running --> Check nginx upstream config
  |
  +-- Check: docker exec nginx curl http://php:9000/ping
        |
        +-- Connection refused --> Wrong listen address
        +-- Timeout --> FPM overloaded, check pm settings

References

For detailed information, load these reference files:

• references/error-solutions.md -- 20+ common Docker PHP errors with solutions