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

# Migration Hook Failed

The `migration.hook_failed` event is triggered when Prelude calls your
[migration hook](/auth/documentation/migration-guide#step-2-migrate-active-users-via-the-migration-hook)
and the call cannot be completed successfully. Use this event to monitor
the health of your migration endpoint and alert on outages or
misconfiguration.

## Failure reasons

The `reason` field identifies the precise rule that failed. It is one of
the following values:

### Transport-level

| Reason                | Description                                                                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `request_failed`      | The HTTP request to your migration hook could not be completed (DNS failure, connection refused, TLS error, timeout exceeding 5 seconds, etc.). |
| `invalid_status_code` | The hook returned a non-2xx HTTP status code.                                                                                                   |

### Response-level

The following reasons are emitted when the hook returns 200 but the body
does not match the expected response schema:

| Reason                   | Description                                                                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_decode_failed` | The response body could not be parsed as JSON (malformed JSON, wrong content type, body exceeding the 64 KB limit, etc.).                                                                    |
| `missing_external_id`    | The response was missing the required `external_id` field on the user.                                                                                                                       |
| `missing_identifiers`    | The response did not provide at least one identifier for the user.                                                                                                                           |
| `invalid_response`       | Fallback emitted when the response body is otherwise invalid — for example an unsupported identifier type, an invalid phone number or email, an unknown OAuth provider, or an invalid scope. |

## Event payload