debugging-docker

Diagnose Docker build failures, runtime errors, and multi-architecture issues.

1|Updated Jul 22, 2025

Search Tags:#debugging #build #platform #docker #ecs #ecr

Ready to run

npx skills add https://github.com/Danik911/thesis_project --skill debugging-docker

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: debugging-docker
Source: https://github.com/Danik911/thesis_project/tree/main/.claude/skills/debugging-docker
Command: npx skills add https://github.com/Danik911/thesis_project --skill debugging-docker

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Systematic debugging workflows for Docker build failures, container runtimes, ECR/ECS pull issues, and cross-platform (ARM64/AMD64/WSL2) challenges.

Core Features & Use Cases

Build & runtime debugging: Identify and fix build errors, runtime crashes, and permission issues.
AWS container troubleshooting: ECR authentication, ECS pull failures, and NAT/subnet considerations.
Platform-aware guidance: Strategies for native vs emulated builds across ARM64/AMD64/WSL2.

Quick Start

Run through a Docker build failure trace and apply the recommended fixes in your Dockerfile and build steps.

Frequently Asked Questions about debugging-docker

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose Docker build failures and fix them?▼

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.

Why is my Docker container crashing at runtime and how do I troubleshoot it?▼

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.

How do I fix ECR authentication and ECS pull failures?▼

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.

Can I build Docker images for ARM64 and AMD64 on different platforms?▼

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.

What are common Docker permission and networking issues in containers?▼

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.

How do I optimize Docker builds and leverage BuildKit caching?▼

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.