Troubleshooting - Grid

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

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.

Getting help

Email support@grid.squads.xyz with the account address and the error’s code and details.

Next Steps

Moving off Grid

Schedule and checklist

Migrate your accounts

Step-by-step signer swap