Docker Build Error Analysis

Analyze Dockerfile and build logs for PHP project build failures and provide targeted fixes.

Common Build Error Patterns

Detection Patterns

1. Extension Compilation Failure

# ERROR: gd extension on Alpine
RUN docker-php-ext-install gd
# configure: error: png.h not found

# FIX (Alpine):
RUN apk add --no-cache libpng-dev libjpeg-turbo-dev freetype-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd

# FIX (Debian):
RUN apt-get update && apt-get install -y libpng-dev libjpeg62-turbo-dev libfreetype6-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd

2. Extension Dependencies by Base Image

3. Memory Exhausted During Build

# ERROR: Composer runs out of memory
RUN composer install
# PHP Fatal error: Allowed memory size of 134217728 bytes exhausted

# FIX: Increase memory limit for Composer
RUN php -d memory_limit=-1 /usr/bin/composer install --no-dev --optimize-autoloader

4. Context Too Large

# Required .dockerignore entries
.git
node_modules
vendor
var/cache
var/log
docker-compose*.yml
.env.local
tests
docs

5. Alpine Build Essentials

RUN apk add --no-cache --virtual .build-deps \
    $PHPIZE_DEPS build-base autoconf \
    && pecl install redis \
    && docker-php-ext-enable redis \
    && apk del .build-deps

Grep Patterns

# Find Dockerfiles with extension installs
Grep: "docker-php-ext-install" --glob "**/Dockerfile*"

# Find missing dev package installs before ext-install
Grep: "ext-install.*(gd|intl|zip|pdo_pgsql|imagick)" --glob "**/Dockerfile*"

# Find unrestricted memory Composer runs
Grep: "composer install|composer update" --glob "**/Dockerfile*"

# Find large base images
Grep: "FROM php:[0-9.]+-apache|FROM php:[0-9.]+-cli$" --glob "**/Dockerfile*"

# Check for .dockerignore existence
Glob: "**/.dockerignore"

Root Cause Analysis

Build Fails on CI but Works Locally

1. Different Docker version — check docker version output
2. No BuildKit — CI may not have DOCKER_BUILDKIT=1
3. Cache differences — CI has cold cache, local has warm
4. Platform mismatch — local ARM (M1/M2), CI AMD64

Extension Fails Only on Alpine

1. musl vs glibc — some extensions require glibc patches
2. Package naming — Alpine uses different package names
3. Missing build tools — add build-base for compilation

Fix Templates

Alpine

RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS <DEV_PACKAGES> \
    && docker-php-ext-configure <EXT> <OPTIONS> \
    && docker-php-ext-install -j$(nproc) <EXT> \
    && apk del .build-deps \
    && apk add --no-cache <RUNTIME_PACKAGES>

Debian

RUN apt-get update \
    && apt-get install -y --no-install-recommends <DEV_PACKAGES> \
    && docker-php-ext-configure <EXT> <OPTIONS> \
    && docker-php-ext-install -j$(nproc) <EXT> \
    && apt-get purge -y --auto-remove <DEV_ONLY_PACKAGES> \
    && rm -rf /var/lib/apt/lists/*

Severity Classification

Output Format

### Build Error: [Category]

**Severity:** Critical/Major/Minor
**Stage:** `FROM ... AS <stage>`
**Line:** Dockerfile:line

**Error Message:**
<exact error from build log>

**Root Cause:**
[Explanation of why the build fails]

**Fix:**
```dockerfile
// Corrected Dockerfile instruction

Prevention: [How to avoid this error in future builds]