Docker Troubleshooting Knowledge Base

Quick reference for debugging Docker containers in PHP projects.

Common Build Errors

Error	Cause	Solution
`failed to compute cache key`	File not in build context	Check `.dockerignore`, verify file path
`returned a non-zero code: 137`	OOM during build	Increase Docker memory or reduce parallel ops
`Could not find package`	Composer can't resolve deps	Check `composer.lock`, mount auth secrets
`E: Unable to locate package`	Missing apt repository	Add required repo or use correct base image
`configure: error: ... not found`	Missing dev library	Install `-dev` package before ext install
`Permission denied`	Wrong user/permissions	Fix `chown`/`chmod` or adjust USER directive
`COPY failed: file not found`	File not in context	Check path relative to Dockerfile, check `.dockerignore`
`max depth exceeded`	Too many layers	Combine RUN commands, use multi-stage build