Docker Build and Runtime Debugging Cheatsheet

Use this as a rapid troubleshooting guide when Docker builds fail, containers crash on startup, or ports are unreachable, so you can systematically isolate the root cause, reduce downtime, and recover service behavior with minimal guesswork instead of thrashing through random rebuilds and shell sessions.

Build Fails Quickly

# Show complete build logs (including intermediate stages)
docker build --progress=plain -t app:debug .
 
# Rebuild without cache to validate stale-layer issues
docker build --no-cache -t app:fresh .

Container Exits Immediately

# See last logs with timestamps
docker logs --timestamps --tail=200 <container>
 
# Start shell in image to verify files and entrypoint
docker run --rm -it --entrypoint sh app:debug

Port Not Reachable

1. Confirm container is listening on expected port.
2. Confirm host mapping exists (-p host:container).
3. Confirm service binds to 0.0.0.0, not 127.0.0.1.

docker ps --format "table {{.Names}}\t{{.Ports}}"

Five Minute Triage Checklist

• Did dependencies install in the same stage where they are used?
• Is the runtime image missing shell/system libs?
• Is NODE_ENV=production hiding required dev tooling?
• Are secrets injected at runtime, not build time?
• Can issue be reproduced locally with same image digest?