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

# Troubleshooting

> Error codes, outages, unknown outcomes and accounts the migration kit does not migrate

Every error the migration kit throws is a `GridMigrationError` with a stable `code`. `retryable` is `true` only when nothing was signed or submitted, so calling the same function again is safe.

## Error codes

| Code | Meaning | What to do |
| - | - | - |
| `VAULT_MISMATCH` | The vault is not vault 0 of the settings account. | Pass the account's vault 0 and its own settings address (`resolveSettingsAddress`). |
| `CONTROLLED_ACCOUNT` | The account has a settings authority, so it cannot be migrated with a sync settings change. | The settings authority changes the signers directly with `buildSetSigners`. |
| `PASSKEY_ACCOUNT` | A signer is off-curve (a passkey session signer). | Passkey accounts are migrated with Squads. Contact support. |
| `TIME_LOCKED_ACCOUNT` | The account has a time lock, so sync execution is not allowed. | Contact support. |
| `NOTHING_TO_MIGRATE` | No Grid signer remains; there is no swap to run. | No swap needed. Run `runCleanup` if `checkMigrated` still reports limits, then switch to the SDK. |
| `GRID_UNAVAILABLE` | Grid answered 5xx or 410, or could not be reached (`NETWORK_ERROR`), before anything was signed. Safe to retry. | Retry later. Nothing was signed. |
| `GRID_REQUEST_FAILED` | The Grid request failed in any other way before anything was signed (a 4xx other than 410, or a malformed answer). Not retryable; `details` holds the original error. | Read `details`, fix the input or the account, then retry. |
| `SETTINGS_ADDRESS_UNAVAILABLE` | Grid returned no settings address for the account (for example, it is still pending). | Retry once the account is active, or contact support. |
| `GRID_TRANSACTION_MISMATCH` | Grid's prepared transaction or its KMS payloads do not match the plan. Nothing was signed. | Do not retry in a loop. Send `details` to support. |
| `SIGNING_FAILED` | The Grid session could not sign. Nothing was submitted. Safe to retry after re-authenticating. | Log the user in again, then retry. Nothing was submitted. |
| `PENDING_NOT_PERSISTED` | An `onBeforeSubmit` hook (for example `useGridMigration`'s) could not store the pending swap. It throws before anything is signed, so nothing was signed or submitted. | Free up or allow `localStorage` (or fix your `onBeforeSubmit`), then retry. Nothing was signed. |
| `INVALID_ARGUMENT` | The input is malformed. | Fix the input; the message names the field. |

Errors from the Smart Account SDK pass through unchanged as `SmartAccountError`.

## Outages and unknown outcomes

| When | What happens | What to do |
| - | - | - |
| Grid is down before anything is signed | `GRID_UNAVAILABLE`, `retryable: true` | Retry later |
| `/submit` fails or times out after signing | The kit resolves the swap on-chain and never resubmits | If the result is `unknown`, call `runMigration` later with `{ pending }` |
| The swap never landed and its blockhash expired | `{ status: 'expired' }` | Safe to plan and run again |

> [!WARNING]
>
> **Never start a second swap while one is pending.** Store `outcome.pending` and resolve it with `runMigration(rpc, session, plan, { pending })`. The React hook does this for you.

## Accounts the kit does not migrate

* **Passkey accounts**: `PASSKEY_ACCOUNT`. Contact us; these move with our help.
* **Controlled accounts**: `CONTROLLED_ACCOUNT`. The settings authority changes the signers directly with `buildSetSigners`.
* **Time-locked accounts**: `TIME_LOCKED_ACCOUNT`. Contact us.
* **Accounts whose signers you already hold**: there is no swap. Replace your calls using the [endpoint map](https://developers.squads.so/grid/v1/migration/after-grid.md#endpoint-map).

## Getting help

Email [support@grid.squads.xyz](mailto:support@grid.squads.xyz) with the account address and the error's `code` and `details`.

## Next Steps

> [card] [Moving off Grid](https://developers.squads.so/grid/v1/migration/overview.md)
>
> Schedule and checklist

> [card] [Migrate your accounts](https://developers.squads.so/grid/v1/migration/migrate-accounts.md)
>
> Step-by-step signer swap


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