Docker CLI Command Hangs When The Daemon Is Frozen

If a developer tool calls docker image inspect, docker compose, or docker system df without a deadline, a frozen Docker Desktop backend can make the tool look broken even when the real incident is disk pressure, Docker.raw growth, or a backend restart.

Docker Desktop did not answer before the 5s deadline.

Please do not reset Docker Desktop yet. First collect read-only evidence:

df -h
ls -lh "$HOME/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw" 2>/dev/null
docker system df -v 2>/dev/null || true

If host disk or Docker.raw is full, prune build cache and unused images before touching named volumes. Named volumes can contain local databases or project state.

Timeout Every Docker Probe

Use a short command-level timeout around Docker probes. A parent app context is not enough if it has no deadline.

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

cmd := exec.CommandContext(ctx, "docker", "image", "inspect", image)

Do Not Collapse These Errors

• Missing image: Docker answered, and the image is not present.
• Timeout: Docker CLI or daemon did not answer before the deadline.
• ENOSPC: host or Docker VM disk is full and writes may fail.
• Volume risk: the user has named volumes or local databases that should not be reset blindly.

User-Facing Recovery Order

1. Show that Docker did not answer before the deadline.
2. Ask for read-only disk evidence: host free space, Docker.raw size, and docker system df -v if it answers.
3. Suggest pruning build cache/images before touching volumes.
4. Warn that Docker Desktop reset removes local images, containers, and volumes.
5. Offer a cleanup plan when the same failure affects onboarding, CI, or multiple developer Macs.