Docker Gotchas

Image Building

• •apt-get update and apt-get install in separate RUN layers = stale packages weeks later — always combine them
• •python:latest today is different than python:latest tomorrow — pin versions like python:3.11.5-slim
• •Multi-stage builds: forgotten --from=builder copies from wrong stage silently
• •COPY before RUN invalidates cache on every file change — copy requirements first, install, then copy code

Runtime Crashes

• •Default log driver has no size limit — one chatty container fills disk and crashes host
• •OOM killer strikes without warning — set memory limits with -m 512m on every container
• •Container runs as root by default — add USER nonroot or security scans fail and platforms reject
• •localhost inside container is container's localhost, not host — bind to 0.0.0.0

Networking

• •Container DNS only works on custom networks — default bridge can't resolve container names
• •Published ports bind to 0.0.0.0 by default — use 127.0.0.1:5432:5432 for local-only
• •Zombie connections from killed containers — set proper health checks and restart policies
• •Port already in use: previous container still stopping — wait or force remove

Compose Traps

• •depends_on waits for container start, not service ready — use condition: service_healthy with healthcheck
• •.env file in wrong directory silently ignored — must be next to docker-compose.yml
• •Volume mounts overwrite container files — empty host dir = empty container dir
• •YAML anchors don't work across files — extends deprecated, use multiple compose files

Volumes and Data

• •Anonymous volumes from Dockerfile VOLUME instruction accumulate silently — use named volumes
• •Bind mounts have host permission issues — container user must match host user or use :z suffix
• •docker system prune doesn't remove named volumes — add -volumes flag explicitly
• •Stopped container data persists until container removed — docker rm deletes data

Resource Leaks

• •Dangling images grow unbounded — docker image prune regularly
• •Build cache grows forever — docker builder prune reclaims space
• •Stopped containers consume disk — docker container prune or --rm on run
• •Networks pile up from compose projects — docker network prune

Secrets and Security

• •ENV and COPY bake secrets into layer history permanently — use secrets mount or runtime env
• •--privileged disables all security — almost never needed, find specific capability instead
• •Images from unknown registries may be malicious — verify sources
• •Build args visible in image history — don't use for secrets

Debugging

• •Exit code 137 = OOM killed, 139 = segfault — check docker inspect --format='{{.State.ExitCode}}'
• •Container won't start: check logs even for failed containers — docker logs <container>
• •No shell in distroless images — docker cp files out or use debug sidecar
• •Inspect filesystem of dead container — docker cp deadcontainer:/path ./local