> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejar fallos de migración con el evento MigrationFailed

> Usa el evento MigrationFailed de Laravel 13 para entender la información de una migración fallida, los límites de las transacciones y el diseño de la monitorización y las pruebas.

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.

| Propiedad | Tipo | Contenido |
| - | - | - |
| `migration` | `Migration` | La instancia de migración que se ejecuta |
| `method` | `string` | El método invocado. Normalmente `up` o `down` |
| `name` | `string\|null` | El nombre de la migración. Puede ser `null` según la ruta de ejecución |
| `exception` | `Throwable` | La excepción que causó el fallo |

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.

```php theme={null}
<?php

namespace App\Providers;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
            Log::error('Database migration failed.', [
                'migration' => $event->name,
                'class' => $event->migration::class,
                'method' => $event->method,
                'connection' => $event->migration->getConnection(),
                'exception' => $event->exception,
            ]);
        });
    }
}
```

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.

```mermaid theme={null}
flowchart TD
    A["MigrationsStarted<br>Inicio del lote"] --> B["MigrationStarted<br>Inicio de una migración"]
    B --> C{"¿up / down tuvo éxito?"}
    C -->|Éxito| D["MigrationEnded<br>Migración completada"]
    D --> E["Siguiente migración"]
    E --> F["MigrationsEnded<br>Lote completado"]
    C -->|Excepción| G["MigrationFailed<br>Contiene la excepción"]
    G --> H["Volver a lanzar la excepción original"]
```

`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.

```php theme={null}
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('orders', function (Blueprint $table): void {
            $table->string('status');
        });
    }
};
```

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.

```php theme={null}
Event::listen(MigrationFailed::class, function (MigrationFailed $event): void {
    $operation = $event->method === 'down' ? 'rollback' : 'migrate';

    Log::critical('Migration operation failed.', [
        'operation' => $operation,
        'migration' => $event->name ?? $event->migration::class,
        'exception' => $event->exception,
    ]);
});
```

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.

```php theme={null}
<?php

namespace Tests\Feature;

use Illuminate\Database\Events\MigrationFailed;
use Illuminate\Support\Facades\Event;
use RuntimeException;
use Tests\TestCase;

class MigrationFailureTest extends TestCase
{
    public function test_failed_migration_dispatches_event(): void
    {
        Event::fake([MigrationFailed::class]);

        $this->artisan('migrate', [
            '--path' => 'tests/Fixtures/migrations/2026_01_01_000000_fail.php',
        ])->assertFailed();

        Event::assertDispatched(MigrationFailed::class, function (MigrationFailed $event): bool {
            return $event->method === 'up'
                && $event->exception instanceof RuntimeException;
        });
    }
}
```

`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

* [Documentación oficial de Laravel: eventos de migración](https://github.com/laravel/docs/blob/13.x/migrations.md#events)
* [Documentación oficial de Laravel: listeners de eventos](https://github.com/laravel/docs/blob/13.x/events.md#registering-events-and-listeners)
* [Framework 13.x: MigrationFailed](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationFailed.php)
* [Framework 13.x: MigrationEvent](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Events/MigrationEvent.php)
* [Framework 13.x: emisión de eventos en Migrator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migrator.php#L435-L460)
* [Framework 13.x: clase base Migration](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Migrations/Migration.php)


## Related topics

- [Migraciones de base de datos](https://kawax.biz/es/migrations.md)
- [Temas avanzados](https://kawax.biz/es/advanced/index.md)
- [Publicación y actualización de migraciones de paquetes](https://kawax.biz/es/advanced/package-migrations.md)
- [Eventos y listeners](https://kawax.biz/es/events.md)
- [Observers de Eloquent y eventos del modelo](https://kawax.biz/es/advanced/eloquent-observers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.