Illuminate\Database\Events\MigrationFailed. When an exception occurs while a single migration runs, Laravel dispatches this event and then rethrows the exception.
This is not a mechanism that reruns migrations automatically. The event exists to pass the name of the failed migration, whether up or down failed, and the original exception on to logs and notifications.
Data the event carries
MigrationFailed extends MigrationEvent and exposes the following values for a single migration.
If you record
migration::class in addition to name, you can identify the migration even on paths where the file name isn’t available. With migration->getConnection(), you can also check the connection name the migration specified explicitly.
Registering a listener
Register the event in your application’s service provider and pass structured context and the original exception to the log.php artisan migrate and php artisan migrate:rollback still exit with a failure.
Dispatch order
For a normal single migration,Migrator dispatches events in the following order.
MigrationEnded is dispatched only when the run succeeds. If the migration’s work, or a listener for an event dispatched during the run, throws an exception, execution enters the exception handling in runMigration and MigrationFailed is dispatched.
When the exception is rethrown in the middle of a batch, the remaining migrations don’t run. As a result, MigrationsEnded isn’t necessarily dispatched for a failed batch. Don’t rely on a single event to handle both batch completion and failure.
Relationship to transactions
When the database’s Schema Grammar supports schema transactions and the migration’swithinTransaction is enabled, Laravel wraps the run in a transaction.
MigrationFailed is dispatched after the transaction rolls back. However, the database can’t always roll back every operation, for example when:
- The database or Schema Grammar you use doesn’t support schema transactions
- The migration sets
public $withinTransaction = false - The database doesn’t treat DDL as transactional
migrations table before recovering.
Telling up and down failures apart
Rollback failures are reported through the same event. Check method to route notifications and runbooks differently for applying and reverting.
down fails, the exception occurs before the migration is removed from the migrations table. Migrator performs the removal only after down completes successfully, so after a failure, check both the actual schema and the record.
Boundaries of monitoring and notifications
MigrationFailed is handled synchronously in the process that ran the deployment or the manual Artisan command. If you queue the notification, you can move its delivery to later processing without hiding the failure of the migration command itself.
However, avoid rerunning the failed migration from the listener. Rerunning it before the same command has finished complicates locks, partially applied DDL, and deployment ordering. When a rerun is necessary, fix the cause, check the state, and then run it as an operational procedure.
Verifying the event in tests
Prepare a test migration that fails, and verify that the Artisan command fails and that the event carries the causing exception. Don’t place test migrations where production migration discovery can find them.Event::fake records events, so you can test separately from your application’s actual notification handling. Verify whether a rollback happens, and that no DDL is left partially applied, in separate integration tests that use your database and Schema Grammar.
Summary
MigrationFailedpassesmigration,method,name, andexceptionwhen a single migration fails.MigrationEndedis dispatched only on success, andMigrationsEndedonly when the batch runs to completion.- Transaction and DDL behavior differs by database, so don’t treat the event as a rollback guarantee.
- Limit listeners to monitoring and notifications, and perform reruns and recovery as an operational procedure after checking the cause and the schema.