docker-errors-build

Quick Reference

Build Error Debugging Workflow

Build fails
  |
  +-- Read the FULL error message (use --progress=plain for details)
  |
  +-- Identify error category:
  |     |
  |     +-- "file not found" / "checksum" --> COPY/ADD path issue (see 1.1)
  |     +-- "context" / "sending build context" slow --> Context too large (see 1.2)
  |     +-- Rebuilds unexpectedly --> Cache invalidation (see 1.3)
  |     +-- "mount" errors --> BuildKit mount config (see 1.4)
  |     +-- "invalid stage" / "not found" --> Multi-stage reference (see 1.5)
  |     +-- "pull access denied" / "manifest unknown" --> Base image (see 1.6)