Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

composer install fails at php artisan package:discover with error code 255

ErrorScript @php artisan package:discover --ansi handling the post-autoload-dump event returned with error code 255

Short answer

Code 255 is only the exit code of a PHP crash inside artisan. The real message is printed above it or hidden. Install without scripts, run artisan package:discover by hand to see the actual error, then fix it: usually a PHP version check, a dev-only provider missing after --no-dev, or a folder Laravel cannot write.

  • Applies to Composer 2.8, PHP 8.3, Laravel 12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Skip the scripts so Composer finishes, then run the failing command yourself. The message it prints is the real error.

    composer install --no-scripts
    php artisan package:discover
  2. 2Match what you see, then jump to its fix

    1. 1The manual run fails with a message about the PHP version or a missing extension, or php -v shows a different version than you expect.The PHP version or an extension fails Composer's platform checkFix
    2. 2Class "...\ServiceProvider" not found, printed by the manual run, right after composer install --no-dev.A development-only provider is still registered but the package was not installedFix
    3. 3The manual run mentions permission denied for a path under bootstrap/cache or storage.Laravel cannot write to its cache foldersFix

What does the error look like?

  • Script @php artisan package:discover --ansi handling the post-autoload-dump event returned with error code 255

Cause 1 of 3

The PHP version or an extension fails Composer's platform check

1Check

Composer writes a platform check into the autoloader. By default it only checks the PHP version; with the setting turned to true it checks extensions too. The command line may also run a different PHP binary than the one you installed with.

php -v
composer check-platform-reqs

2Fix

Run Composer with a PHP that satisfies the locked packages, or install the missing extension. Do not hide the problem by disabling the check on a server that really lacks the extension.

# see which platform packages Composer sees
composer show --platform

3Verify

The check passes and discovery runs.

composer check-platform-reqs
php artisan package:discover

Confirmed by getcomposer.org

Did this fix it?

Cause 2 of 3

A development-only provider is still registered but the package was not installed

1Check

Laravel loads the providers listed in bootstrap/providers.php. If a dev package (a debug bar, an IDE helper) is listed there by hand and you install with --no-dev, its class does not exist.

cat bootstrap/providers.php
composer show | grep -i debugbar

2Fix

Remove the dev package's provider from the list. Packages that support discovery register themselves, so they need no manual line.

// bootstrap/providers.php: keep only providers of installed packages
return [
    App\Providers\AppServiceProvider::class,
];

3Verify

Production install finishes without scripts being skipped.

composer install --no-dev

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

Laravel cannot write to its cache folders

1Check

Laravel must write to bootstrap/cache and storage, so the user running Composer (and the web server user) needs write access.

ls -ld bootstrap/cache storage storage/framework/*

2Fix

Give the account that runs Composer and the web server user write access to both folders. The owner and group below are examples.

sudo chown -R "$USER":www-data storage bootstrap/cache
chmod -R ug+rwX storage bootstrap/cache

3Verify

Discovery now completes.

php artisan package:discover

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Install and run the app as the same deploy user, never mixing root and www-data.
  • Pin the PHP version in composer.json (config.platform.php) so a lock file built elsewhere still fits the server.
  • Keep dev-only providers out of bootstrap/providers.php.
  • In CI, run composer install --no-scripts first, then artisan commands, so errors show up clearly.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.