Debugging Docker Operations

Overview

Systematic troubleshooting workflows for Docker build failures, runtime errors, AWS container services, platform-specific issues, and performance optimization. Designed for multi-platform environments (ARM64/AMD64/WSL2) with pharmaceutical compliance contexts requiring GAMP-5 validation.

When to Use

• Build Failures: Package installation errors, COPY failures, layer caching issues
• Runtime Errors: Container crashes, exit codes, DNS resolution, port conflicts
• AWS Container Services: ECR authentication, ECS pull failures, rate limiting
• Platform Issues: ARM64 vs AMD64 emulation, WSL2 integration, cross-platform builds
• Performance Problems: Slow builds, large images, QEMU emulation overhead
• Volumes/Networking: Permission errors, mount failures, port binding

Available Tools

Standard Tools

AWS MCP Tools

Core Workflow

Phase 1: Symptom Diagnosis

Objective: Identify problem category and gather diagnostic information

1. Identify Problem Type

   bash
   1# For build failures
   2docker build 2>&1 | tee build.log
   3
   4# For runtime errors
   5docker logs <container-name>
   6docker inspect <container-name>
   7
   8# For AWS issues
   9aws ecr describe-repositories
   10aws ecs describe-tasks --cluster <cluster> --tasks <task-arn>

2. Categorize the Issue

   • Build Failure (exit during docker build)
   • Runtime Error (container exits or crashes)
   • AWS ECR/ECS Issue (authentication, pull failures)
   • Platform/Architecture Issue (ARM64/AMD64 mismatch)
   • Performance Problem (slow or inefficient)
   • Networking/Volume Issue

3. Collect Context

   bash
   1docker version && docker info | head -30
   2uname -m  # Platform: x86_64 or aarch64

Quality Gate: Problem type identified, initial logs collected

Phase 2: Root Cause Analysis

Build Failures

Common Patterns:

bash
1# Check build log for specific failures
2grep -E "ERROR|failed|error:" build.log
3
4# Common patterns:
5# "COPY failed" → File not in build context
6# "returned a non-zero code" → Command failed
7# "no matching manifest" → Platform mismatch

Key Checks:

• Build context: ls -la <path-to-file>
• .dockerignore: cat .dockerignore
• Layer caching: docker build --no-cache

See reference/common-errors.md for complete error matrix.

Runtime Errors

Exit Code Quick Reference:

Diagnosis:

bash
1docker inspect <container> | jq '.[0].State'
2docker logs --tail 100 <container>

AWS ECR/ECS Issues

ECR Authentication:

Error: "no basic auth credentials"

• Cause: ECR login token expired (12-hour validity)
• Fix:

  bash
  1aws ecr get-login-password --region eu-west-2 | \
  2  docker login --username AWS --password-stdin \
  3  <account-id>.dkr.ecr.eu-west-2.amazonaws.com

ECS Pull Failures:

Error: "CannotPullContainerError"

• Checklist:
  1. Task execution role has ECR permissions
  2. VPC has NAT Gateway (for private subnets)
  3. Image tag exists in ECR

Using AWS MCP:

# Check ECR images
mcp__aws-api-mcp__call_aws: aws ecr describe-images --repository-name <repo>

# Check ECS task failures
mcp__aws-api-mcp__call_aws: aws ecs describe-tasks --cluster <cluster> --tasks <task-arn>

See reference/aws-ecr-ecs.md for complete AWS troubleshooting guide.

Platform/Architecture Issues

Slow Build Detection:

bash
1# Check if emulation is active (ARM64 host building AMD64)
2docker run --rm --platform=linux/amd64 alpine uname -m
3# If output shows x86_64 on ARM64 host → emulation active (slow)

Solutions:

1. Use native platform for development
2. Build target platform only for deployment
3. Use multi-stage with ${BUILDPLATFORM}

See reference/platform-guide.md for complete platform guidance.

Quality Gate: Root cause identified, specific error patterns documented

Phase 3: Solution & Validation

Build Failure Fixes

dockerfile
1# Fix missing file in context
2# Verify path exists: ls -la <path>
3COPY main.py /app/
4
5# Fix package installation with retry
6RUN pip install --no-cache-dir -r requirements.txt || \
7    (pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt)
8
9# Fix platform issues
10# docker build --platform=linux/amd64 -t image:prod .

Runtime Error Fixes

bash
1# Fix permission issues
2docker run --user $(id -u):$(id -g) image:tag
3
4# Fix OOM (Exit 137)
5docker run -m 2g --memory-swap 2g image:tag
6
7# Fix port conflicts
8docker run -p 8081:8080 image:tag  # Change host port

AWS Fixes

bash
1# Refresh ECR credentials
2aws ecr get-login-password --region eu-west-2 | docker login --username AWS --password-stdin <account>.dkr.ecr.eu-west-2.amazonaws.com
3
4# Fix Docker Hub rate limiting - use ECR Public
5# FROM public.ecr.aws/docker/library/python:3.12-slim

Validation

bash
1# Rebuild with verbose output
2docker build --progress=plain -f Dockerfile -t image:test .
3
4# Test container startup
5docker run --rm image:test
6
7# Verify functionality
8docker run -it image:test /bin/sh -c "command-to-test"

Quality Gate: Fix applied, container builds and runs without errors

Quick Reference Table

Best Practices

Build Optimization

• Layer ordering: Dependencies before code (cache efficiency)
• Multi-stage builds: Separate build and runtime environments
• Use .dockerignore: Exclude node_modules, .git, __pycache__

Security

dockerfile
1# Non-root user
2RUN adduser -D appuser
3USER appuser
4
5# Never COPY secrets - use --secret flag

Platform Handling

bash
1# Development (native platform - fast)
2docker build -t image:dev .
3
4# Production (target platform)
5docker build --platform=linux/amd64 -t image:prod .
6
7# Multi-platform with cache
8docker buildx build \
9  --platform linux/amd64,linux/arm64 \
10  --cache-from type=registry,ref=<repo>:cache \
11  --cache-to type=registry,ref=<repo>:cache \
12  -t image:multi --push .

WSL2 Performance

• Store projects in WSL2 filesystem (~/), NOT Windows mount (/mnt/c/)
• Configure .wslconfig with memory limits
• Use wsl --shutdown to reclaim memory

See reference/wsl2-optimization.md for complete WSL2 guide.

Common Pitfalls

Don't: Use relative paths without verification

dockerfile
1# WRONG - may fail if context is incorrect
2COPY ../app/file.py /app/
3
4# RIGHT - relative to build context root
5COPY app/file.py /app/

Do: Use explicit platform for production

bash
1# WRONG - platform inferred (may differ from prod)
2docker build -t api:latest .
3
4# RIGHT - explicit platform
5docker build --platform=linux/amd64 -t api:latest .

Do: Verify volume mounts work

bash
1# Check if container sees host files
2docker exec <container> ls -la /app/
3
4# Recreate containers after mount changes
5docker-compose down && docker-compose up -d

Quality Checklist

• Problem type identified (build/runtime/AWS/platform/network/volume)
• Diagnostic logs collected and analyzed
• Root cause determined with specific error patterns
• Solution applied with appropriate fix
• Build succeeds without errors
• Container starts and runs successfully
• Functionality validated
• Platform architecture verified (matches deployment target)
• Security checked (non-root user, no exposed secrets)

Detailed References

• Docker Commands: reference/docker-commands.md
• Common Error Matrix: reference/common-errors.md (20+ error patterns)
• AWS ECR/ECS Guide: reference/aws-ecr-ecs.md
• Platform Guide: reference/platform-guide.md (ARM64/AMD64/WSL2, buildx caching)
• WSL2 Optimization: reference/wsl2-optimization.md
• Build Optimization: reference/build-optimization.md
• Security Hardening: reference/security-hardening.md

Diagnostic Scripts

• Build Failure Analysis: scripts/analyze-build-failure.sh <log-file>
• Container Inspection: scripts/inspect-container.sh <container-name>
• Platform Check: scripts/check-platform.sh

Remember: Docker issues are systematic and diagnosable. Follow the three-phase workflow (Symptom → Root Cause → Solution), use AWS MCP tools for ECR/ECS issues, and reference the detailed guides for complex scenarios. Always validate fixes before considering the issue resolved.