Saltar al contenido principal
Si quieres monitorizar los fallos de migración, escucha Illuminate\Database\Events\MigrationFailed. Cuando se produce una excepción durante la ejecución de una migración individual, Laravel emite este evento y después vuelve a lanzar la excepción. No es un mecanismo que vuelva a ejecutar migraciones automáticamente. Es un evento para pasar a los logs y notificaciones el nombre de la migración fallida, si falló up o down, y la excepción original.

Información que contiene el evento

MigrationFailed hereda de MigrationEvent y expone los siguientes valores sobre una migración individual. Si registras migration::class además de name, podrás identificar la migración incluso en rutas donde no se puede obtener el nombre del archivo. Con migration->getConnection() también puedes comprobar el nombre de conexión que la migración especificó explícitamente.

Registrar un listener

Registra el evento en el service provider de tu aplicación y pasa al log el contexto estructurado y la excepción original.
Haz que el listener se centre en registrar el fallo y no modifiques el esquema ni vuelvas a ejecutar migraciones desde él. Como la excepción original se vuelve a lanzar después del evento, php artisan migrate y php artisan migrate:rollback siguen terminando con fallo.

Orden de emisión

En una migración individual normal, Migrator emite los eventos en el siguiente orden. MigrationEnded solo se emite cuando la ejecución tiene éxito. Si el procesamiento de la migración, o un listener de un evento emitido durante la ejecución, lanza una excepción, se entra en el manejo de excepciones de runMigration y se emite MigrationFailed. Además, si la excepción se vuelve a lanzar en medio de un lote, las migraciones restantes no se ejecutan. Por eso, no siempre se emite MigrationsEnded para un lote fallido. No manejes la finalización del lote y el fallo con un único evento.

Relación con las transacciones

Cuando el Schema Grammar de la base de datos admite transacciones de esquema y withinTransaction de la migración está activado, Laravel envuelve la ejecución en una transacción.
Si el procesamiento falla en esta ruta, MigrationFailed se emite después del rollback de la transacción. Sin embargo, en los siguientes casos la base de datos no siempre puede revertir todas las operaciones:
  • La base de datos o el Schema Grammar que usas no admite transacciones de esquema
  • La migración especifica public $withinTransaction = false
  • La base de datos no trata el DDL como transaccional
Por tanto, no concluyas que el esquema ha vuelto a su estado original solo porque recibiste este evento. En el entorno donde falló, comprueba el esquema real y el estado de la tabla migrations antes de recuperarlo.

Distinguir los fallos de up y down

Los fallos de rollback también se notifican con el mismo evento. Comprueba method para separar los destinos de notificación y los procedimientos operativos al aplicar y al revertir.
Cuando falla down, la excepción se produce antes de que la migración se elimine de la tabla migrations. Migrator realiza la eliminación solo después de que down termine correctamente, así que tras un fallo comprueba tanto el esquema real como el registro.

Límites de la monitorización y las notificaciones

MigrationFailed se procesa de forma síncrona en el proceso que ejecutó el despliegue o el comando Artisan manual. Si encolas la notificación, puedes separar su entrega en un procesamiento posterior sin ocultar el fallo del propio comando de migración. Sin embargo, evita volver a ejecutar la migración fallida desde el listener. Volver a ejecutarla mientras el mismo comando no ha terminado complica los bloqueos, el DDL aplicado parcialmente y el orden del despliegue. Si es necesario volver a ejecutarla, corrige la causa, comprueba el estado y ejecútala como procedimiento operativo.

Comprobar el evento en las pruebas

Prepara una migración de prueba que falle y comprueba que el comando Artisan falla y que el evento contiene la excepción causante. No coloques las migraciones de prueba donde las encuentre la búsqueda de producción.
Event::fake registra los eventos, así que puedes probar por separado del procesamiento real de notificaciones de la aplicación. Comprueba si hay rollback, y que no quede DDL aplicado parcialmente, en pruebas de integración separadas que usen tu base de datos y tu Schema Grammar.

Resumen

  • MigrationFailed pasa migration, method, name y exception cuando falla una migración individual.
  • MigrationEnded solo se emite en caso de éxito, y MigrationsEnded solo cuando el lote se completa hasta el final.
  • El comportamiento de las transacciones y del DDL varía según la base de datos, así que no trates el evento como una garantía de rollback.
  • Limita los listeners a la monitorización y las notificaciones, y realiza las reejecuciones y la recuperación como procedimiento operativo después de comprobar la causa y el esquema.

Fuentes primarias consultadas

Última modificación el 15 de noviembre de 2026