debugging-docker

Docker build failures stem from missing dependencies, incorrect base images, or build context issues. Diagnose by examining build logs for the first error, verify your Dockerfile syntax, check that required files exist in the build context, and use `docker build --progress=plain` to see detailed output. Apply fixes to your Dockerfile and rebuild incrementally.

Runtime crashes occur from missing environment variables, permission issues, or misconfigured volumes. Run `docker logs <container>` to view error output, inspect volume mounts with `docker inspect`, and verify file permissions match container user expectations. Test locally before deploying to ECR/ECS.

ECR pull failures typically result from missing IAM permissions, expired credentials, or incorrect repository URIs. Verify IAM roles grant `ecr:GetDownloadUrlForLayer` and `ecr:BatchGetImage`, confirm your ECS task execution role has ECR permissions, and check that the image URI matches your registry and repository name exactly.

Multi-platform Docker builds require BuildKit and `docker buildx` to target ARM64/AMD64/WSL2 simultaneously. Enable BuildKit with `DOCKER_BUILDKIT=1`, use `docker buildx create --use`, then build with `--platform linux/arm64,linux/amd64`. Native builds are faster; emulation on mismatched platforms is slower but functional.

Permission issues arise when container processes lack read/write access to mounted volumes; fix by adjusting ownership with `chown` or running the container as the correct user. Networking problems stem from misconfigured ports, missing service DNS names, or firewall rules; verify with `docker network inspect` and test connectivity inside the container.

BuildKit caching reduces build time by reusing layers from previous builds. Structure Dockerfiles to place frequently-changing instructions last, use `--cache-from` to reuse external cache, and enable inline cache with `--build-arg BUILDKIT_INLINE_CACHE=1`. Multi-stage builds further reduce image size by discarding build dependencies.