Composer "Script ... returned with error code" in CI

Composer ran a script bound to a lifecycle event (e.g. post-install-cmd, post-autoload-dump) and that script exited non-zero, so Composer reports the event failed and aborts. The dependency download usually succeeded - the failure is in your script.

What this error means

composer install finishes downloading, then fails while running a configured script, printing "Script <cmd> handling the <event> event returned with error code N". The underlying command’s own error appears just above.

composer output

> @php artisan package:discover --ansi

In ProviderRepository.php line 208:
  Class "App\Providers\MissingServiceProvider" not found

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

Common causes

The wrapped command itself failed

A scripts entry (e.g. an Artisan, Symfony, or build command) exited non-zero - a missing class, missing env var, or runtime error inside it. Composer just surfaces that exit code.

Script runs before its prerequisites exist in CI

A post-install script needs an env var, a generated file, or a service not present in CI, so it fails where it would succeed locally.

How to fix it

Read the inner error above the script line

The real failure is the command’s own output; fix that. Reproduce by running the script directly.

Terminal

composer run-script post-autoload-dump
# or run the underlying command to see its full error
php artisan package:discover --ansi

Provide the script’s prerequisites in CI

Set any env vars the script needs (e.g. a .env for Artisan) before composer install.
Order steps so generated files/services exist when the script runs.
If the script is not needed in CI, skip scripts deliberately.

Skip scripts only when appropriate

For a pure dependency-fetch step where post-install commands are not required, disable scripts.