Docker Troubleshooting Knowledge

Docker Troubleshooting Knowledge Base

Quick reference for debugging Docker containers in PHP projects.

Common Build Errors

Common Runtime Errors

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.