Laravel

Fixing Composer 'Your lock file does not contain a compatible set of packages' & Platform Requirement Errors in Laravel & Docker


When deploying a Laravel application to a production Ubuntu server, building a Docker image, or running a GitHub Actions CI/CD workflow, composer install frequently halts with a dependency resolution error:

Installing dependencies from lock file (including require-dev)
Verifying lock file contents can be installed on current platform.
Your lock file does not contain a compatible set of packages. Please run composer update.

  Problem 1
    - Root composer.json requires php ^8.2 but your php version (8.1.29) does not satisfy that requirement.
  Problem 2
    - laravel/framework[v11.30.0] requires ext-pcntl * -> it is missing from your system. Install or enable PHP's pcntl extension.
  Problem 3
    - spatie/laravel-medialibrary[11.9.2] requires ext-intl * -> it is missing from your system. Install or enable PHP's intl extension.

Or, when running composer update or composer require on a low-RAM VPS or container, Composer crashes mid-resolution:

PHP Fatal error: Allowed memory size of 1610612736 bytes exhausted (tried to allocate 4096 bytes) in phar:///usr/local/bin/composer/src/Composer/DependencyResolver/RuleSetGenerator.php on line 129

These errors occur because composer.lock records the exact PHP version and active C extensions of the machine that generated the lockfile. If your production server or Docker container runs a slightly older PHP binary or lacks a required extension, Composer refuses to install the locked packages to prevent runtime crashes.


Quick Diagnostic Reference

Match your exact Composer error message to jump directly to the permanent fix:

Composer Error Signature Root Cause Jump to Fix
requires php ^8.3 but your php version (8.2.x) does not satisfy CLI PHP binary (php -v) differs from PHP-FPM version, or local machine is ahead of server Fix 1
requires ext-intl * / ext-zip * / ext-gd * -> missing from your system Required PHP C extension is not installed or enabled in CLI php.ini / Dockerfile Fix 2
Using --ignore-platform-reqs in CI/CD or Docker builds Masks missing extensions during build, causing fatal Class not found crashes in production Fix 3
Allowed memory size of X bytes exhausted in DependencyResolver composer update SAT solver exceeded default 1.5G PHP CLI memory limit Fix 4

1. Fixing PHP Version Mismatches Between Local, CLI & Production

A common scenario on Ubuntu VPS environments is installing PHP 8.3 for Nginx (php8.3-fpm), while the default terminal /usr/bin/php symlink still points to an older PHP 8.1 or 8.2 binary. When you run composer install, Composer inspects the CLI binary and rejects the lockfile.

Step 1: Check Your Default CLI PHP Version

Verify which PHP binary Composer is actually executing:

php -v
which php

If php -v shows an older version than your web server uses, switch the default Ubuntu CLI binary using update-alternatives:

sudo update-alternatives --set php /usr/bin/php8.3
sudo update-alternatives --set phar /usr/bin/phar8.3
sudo update-alternatives --set phar.phar /usr/bin/phar.phar8.3

Alternatively, invoke Composer explicitly with the desired PHP binary:

/usr/bin/php8.3 /usr/local/bin/composer install --no-dev --optimize-autoloader

(Note: After aligning your PHP CLI version on Ubuntu, ensure your Nginx server block points to the matching PHP-FPM Unix socket so web traffic doesn’t fail. See our guide on Fixing 502 Bad Gateway (Nginx & PHP-FPM) in Laravel, Ubuntu & Docker).

Step 2: Lock the Target Platform in composer.json

If your local machine runs PHP 8.4, but your production server or Docker container runs PHP 8.3.14, running composer update locally will pull package versions that require PHP 8.4—breaking your production deployment.

Prevent this permanently by pinning config.platform.php inside your composer.json to match your production server’s exact PHP version:

{
    "config": {
        "optimize-autoloader": true,
        "preferred-install": "dist",
        "sort-packages": true,
        "platform": {
            "php": "8.3.14"
        }
    }
}

After adding config.platform, regenerate your composer.lock file so Composer resolves dependencies strictly compatible with PHP 8.3.14:

composer update --lock

2. Fixing Missing PHP Extensions (ext-intl, ext-zip, ext-gd, ext-bcmath)

When Composer reports requires ext-intl * -> it is missing from your system, you can inspect which extensions are currently loaded versus missing by running:

composer check-platform-reqs

Example output:

ext-bcmath    8.3.14    success
ext-ctype     8.3.14    success
ext-curl      8.3.14    success
ext-dom       20031129  success
ext-intl      *         missing
ext-zip       *         missing
php           8.3.14    success

Fix A: Ubuntu / Debian Production Servers

Install the missing extensions for your active PHP version via apt:

sudo apt update
sudo apt install -y \
    php8.3-intl \
    php8.3-zip \
    php8.3-gd \
    php8.3-bcmath \
    php8.3-mbstring \
    php8.3-xml \
    php8.3-curl \
    php8.3-mysql

sudo systemctl restart php8.3-fpm

Fix B: Windows (Native PHP, XAMPP, Laragon)

On Windows, open your active php.ini file (find its path with php --ini), locate the semicolon-commented extension lines, and remove the leading ;:

; ❌ Disabled:
;extension=intl
;extension=zip
;extension=gd

; ✅ Enabled:
extension=intl
extension=zip
extension=gd

(Note: While editing php.ini on Windows, ensure curl.cainfo points to a valid cacert.pem bundle so Composer and Guzzle don’t fail on HTTPS downloads. Check our guide on Fixing cURL error 60: SSL certificate problem in Laravel & Docker).

Fix C: Official PHP Docker Images (php:8.3-fpm / php:8.3-cli-alpine)

Minimal Docker images do not ship with intl, zip, gd, or pcntl compiled in. Instead of writing complex apt-get blocks for C header libraries (libicu-dev, libzip-dev, libpng-dev), use the official docker-php-ext-install helper or install-php-extensions:

FROM php:8.3-fpm-alpine

# Install system build dependencies and compile required Laravel extensions
RUN apk add --no-cache \
    icu-dev \
    libzip-dev \
    libpng-dev \
    oniguruma-dev \
    && docker-php-ext-install -j$(nproc) \
    intl \
    zip \
    gd \
    bcmath \
    pcntl \
    pdo_mysql \
    opcache

# Copy Composer binary from official Composer image
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

(Security Note: Always pull fresh upstream php:8.3-fpm or 8.4-fpm tags when rebuilding your containers to protect against SAPI heap vulnerabilities. See How to Patch PHP2Shell (CVE-2026-109618 & CVE-2026-109619) in Ubuntu, Docker & Laravel).


3. The --ignore-platform-reqs Trap (What to Use Instead)

Many Stack Overflow answers advise bypassing Composer errors by appending --ignore-platform-reqs:

# ❌ DANGEROUS IN PRODUCTION DEPLOYMENTS
composer install --ignore-platform-reqs

Why This Breaks Production

Passing --ignore-platform-reqs disables all version and extension checks, including the core PHP version check. If a package requires ext-intl’s NumberFormatter class or PHP 8.3 typed class constants, Composer will install it silently, and your Laravel app will crash with a 500 Fatal Error the moment a user visits a route that calls Number::currency().

Safe Alternative: Scoped --ignore-platform-req

If you are building a vendor artifact inside a lightweight CI runner (such as a GitHub Actions step or a multi-stage Docker composer build stage) that only lacks a queue-specific extension like ext-pcntl or ext-redis which is present on your final runtime container, ignore only that single extension:

# ✅ SAFE FOR MULTI-STAGE BUILDS: Ignores only ext-pcntl and ext-redis while enforcing PHP version
composer install --no-dev --prefer-dist --optimize-autoloader --ignore-platform-req=ext-pcntl --ignore-platform-req=ext-redis

4. Fixing Allowed memory size exhausted During composer update

When you run composer update or composer require, Composer loads the entire dependency graph from Packagist into memory and runs a boolean satisfiability (SAT) solver. On a 1 GB or 2 GB VPS, this easily exceeds PHP’s memory ceiling.

Solution 1: Run composer install (Not composer update) on Production

Never run composer update on a production server. Always run composer update on your local development machine, commit the updated composer.lock file to Git, and run composer install on production:

# Reads directly from composer.lock using less than 40MB of RAM:
composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction

(Note: If your queue workers or web routes throw memory exhaustion errors after deployment, rather than Composer itself, consult our guide on Fixing ‘Allowed memory size of bytes exhausted’ & Queue Worker Timeouts in Laravel).

Solution 2: Prefix With COMPOSER_MEMORY_LIMIT=-1

If you must run composer update or composer require on a constrained environment, override Composer’s internal memory limit for that single command:

COMPOSER_MEMORY_LIMIT=-1 composer update

If your server only has 1 GB of physical RAM and Linux’s OOM Killer terminates the process with Killed (exit code 137), create a temporary 2 GB swap file on Ubuntu so the OS doesn’t kill PHP:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

(Note: Never run composer install as root inside /var/www/html on a Linux server, or Composer will create vendor/ and storage/framework/cache files owned by root, locking out www-data. If you accidentally ran Composer as root, fix ownership immediately using Fixing storage/logs/laravel.log Permission Denied in Linux & Docker).


Verification: Validate Your Lockfile & Platform State

Run these two diagnostic commands in your project root to confirm your composer.json, composer.lock, and installed PHP extensions are 100% synchronized:

# 1. Verify composer.json and composer.lock are in sync and valid
composer validate --strict

# 2. Verify every required PHP version and C extension is active
composer check-platform-reqs

When composer check-platform-reqs outputs success in green across every row, your production deployments and Docker builds will execute cleanly without lockfile or platform errors.