composer install fails at php artisan package:discover with error code 255
Script @php artisan package:discover --ansi handling the post-autoload-dump event returned with error code 255Short 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.
Fix it fast
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:discover2Match what you see, then jump to its fix
- 1
The 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
Class "...\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
The manual run mentions permission denied for a path under bootstrap/cache or storage.Laravel cannot write to its cache foldersFix
- 1
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-reqs2Fix
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 --platform3Verify
The check passes and discovery runs.
composer check-platform-reqs
php artisan package:discoverConfirmed by getcomposer.org
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 debugbar2Fix
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-devConfirmed by laravel.com
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/cache3Verify
Discovery now completes.
php artisan package:discoverConfirmed by laravel.com
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 says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack 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 fixBack end
composer install says the lock file is not compatible and asks for update
Your lock file does not contain a compatible set of packages. Please run composer update.
composer install checked the locked packages against this machine's PHP and extensions and found a conflict.
3 causes, each with a fixBack 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 fixBack end
composer require laravel/passport stops with 'requirements could not be resolved'
... but these were not loaded, likely because it conflicts with another require.
Composer found no Passport release that fits your project at once.
4 causes, each with a fixBack end
Composer says the root composer.json requires a PHP version your PHP does not satisfy
Your requirements could not be resolved to an installable set of packages.
Composer compares the php constraint in your composer.json, or in a package, with the PHP that runs Composer.
3 causes, each with a fix