> ## Documentation Index > Fetch the complete documentation index at: https://docs.rhinestone.dev/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Handle SDK errors and diagnose account, session, recovery, and intent failures. Import typed errors and guards from `@rhinestone/sdk/errors`. Orchestrator errors include a `code`, `statusCode`, and `traceId`; include the trace ID when contacting support. ```ts theme={null} import { isAccountError, isExecutionError, isOrchestratorError, isRateLimited, isRetryable, isSimulationFailed, isValidationError, } from "@rhinestone/sdk/errors"; try { const prepared = await rhinestoneAccount.prepareTransaction(transaction); const signed = await rhinestoneAccount.signTransaction(prepared); const result = await rhinestoneAccount.submitTransaction(signed); await rhinestoneAccount.waitForExecution(result); } catch (error) { if (isRateLimited(error)) { scheduleRetry(error.retryAfter); } else if (isSimulationFailed(error)) { console.error(error.category, error.errorName, error.simulations); } else if (isValidationError(error)) { console.error(error.issues); } else if (isRetryable(error)) { scheduleRetry(); } else if (isOrchestratorError(error)) { console.error(error.code, error.traceId); } else if (error instanceof Error) { console.error(error.message); } } ``` Retry only an idempotent operation. Do not resubmit a signed transaction unless you have confirmed that the previous submission was not accepted. ## Account configuration errors | Error | Cause | Fix | | ----------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `OwnersFieldRequiredError` | A smart account was created without `owners`. | Pass a supported owner set to `createAccount`. | | `Eip7702AccountMustHaveEoaError` | An EIP-7702 account has no EOA signer. | Pass the delegated EOA in `eoa`. | | `Eip7702NotSupportedForAccountError` | The selected account implementation cannot use EIP-7702. | Choose a supported implementation or remove EIP-7702. | | `EoaAccountMustHaveAccountError` | EOA mode has no signer account. | Pass `account` in the EOA configuration. | | `WalletClientNoConnectedAccountError` | A wallet client has no default connected account. | Connect the wallet and construct the client with an account. | | `EoaSigningMethodNotConfiguredError` | The EOA adapter is missing a required signing callback. | Implement the named signing method. | | `EoaSigningNotSupportedError` | EOA mode was asked to create a packed smart-account signature. | Sign with the EOA directly or use a smart account. | | `PasskeyConfigurationNotInstallableError` | The passkey owner set cannot initialize a new account. | Check the passkey count, threshold, and account implementation. | | `ModuleInstallationNotSupportedError` | The account implementation cannot install the requested module. | Use a modular account or remove the module configuration. | | `DefaultValidatorAlreadyInitializedError` | Code tried to enable ECDSA twice. | Use `addOwner`, `removeOwner`, or `changeThreshold`. | | `Eip712DomainNotAvailableError` | The account cannot expose the domain required for typed-data signing. | Use a supported validator or signing path. | | `AccountConfigurationNotSupportedError` | The selected account and module combination is unsupported. | Change the configuration before deployment. | | `FactoryArgsNotAvailableError` | Deployment data could not be derived. | Confirm the account configuration; report a reproducible SDK issue if it persists. | | `SigningNotSupportedForAccountError` | The account implementation cannot sign messages. | Use a supported smart-account validator or the account's native signer. | Catch the category with `isAccountError(error)`. ## Transaction and signing errors | Error | Cause | Fix | | ------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `Eip7702InitSignatureRequiredError` | Transaction preparation needs an EIP-7702 initialization signature, even for an already deployed account. | Call `signEip7702InitData()` and pass the result as `eip7702InitSignature` when preparing. | | `OrderPathRequiredForIntentsError` | Submission did not originate from a prepared intent. | Call `prepareTransaction`, then sign and submit its result. | | `QuoteNotInPreparedTransactionError` | The chosen intent ID does not belong to the prepared response. | Re-prepare or select an ID from `prepared.quotes.all`. | | `InvalidSourceCallsError` | `sourceCalls` names a chain outside `sourceChains`. | Add the chain to `sourceChains` or remove those calls. | | `SignerNotSupportedError` | A guardian signer was used with the intent transaction flow. | Send a UserOperation for guardian recovery. | | `UnknownOwnerError` | Independent signing used an account outside the configured owner set. | Pass an exact configured owner and the matching MFA validator ID. | | `InvalidOwnerSigningOptionsError` | `validatorId` was omitted, unnecessary, or pointed at the wrong MFA factor. | Pass it only for the factor containing that owner. | | `MismatchedOwnerSignaturesError` | Owner contributions cover different prepared transactions or quotes. | Redistribute one prepared payload and collect signatures again. | | `InsufficientOwnerSignaturesError` | The assembled contributions do not meet the account threshold. | Collect the missing signatures before `assembleTransaction`. | | `IndependentSigningNotSupportedError` | The selected validator or transaction shape cannot be assembled independently. | Use the standard `signTransaction(prepared)` flow. | | `IntentFailedError` | A submitted intent reached a failed terminal state. | Inspect `error.context.operations` and `error.context.refunds`; a refunded intent is still failed. Re-prepare before retrying. | Catch the category with `isExecutionError(error)`. ## API and quote errors | Error | Action | | --------------------------------- | -------------------------------------------------------------------------------------------------------- | | `ValidationError` | Inspect `issues` and correct the named request fields. | | `UnauthorizedError` | Check that the API key is valid and sent through `auth: { mode: 'apiKey', apiKey }`. | | `ForbiddenError` | Confirm that the project and requested operation are allowed. | | `KeyScopeDeniedError` | Compare `scope`, `required`, and `actual`, then widen the key scope if appropriate. | | `InsufficientLiquidityError` | Inspect `unfillable` and `availableIntents`; reduce or change the requested assets. | | `SponsorLimitExceededError` | Raise the configured sponsorship cap or make the intent cheaper. Adding balance does not change the cap. | | `InsufficientSponsorBalanceError` | Top up the sponsorship balance for the categories in `failedCategories`. | | `SimulationFailedError` | Inspect `category`, `errorName`, `errorArgs`, and `simulations`. Retry only when `retryable` is true. | | `RateLimitedError` | Wait for `retryAfter`. Rate limits are not included in `isRetryable`. | | `SettlementQuoteError` | Re-prepare later or change the route inputs. | | `SettlementExecutionError` | Check the returned intent status before retrying. | | `ExternalServiceTimeoutError` | Retry an idempotent request with backoff. | | `RelayerMarketUnavailableError` | Retry later with backoff. | | `InternalServerError` | Retry an idempotent request and report the `traceId` if it persists. | | `NotFoundError` | Check the requested intent or resource ID. | | `ConflictError` | Refresh state before retrying the operation. | | `UnprocessableContentError` | Inspect `details`; the request is valid JSON but cannot be fulfilled as submitted. | `isRetryable(error)` returns true for internal errors, upstream timeouts, unavailable relayers, and simulation failures explicitly marked retryable. Use `isSponsorError`, `isSponsorLimitExceeded`, and `isInsufficientSponsorBalance` to distinguish sponsorship failures. Follow [sponsorship setup](/transactions/sponsorship/set-up) for balance and policy configuration. ## Registry errors | Error | Fix | | ----------------------- | --------------------------------------------------------- | | `UnsupportedChainError` | Choose a chain returned by the current SDK chain catalog. | | `UnsupportedTokenError` | Use a token supported on that chain for `tokenRequests`. | These are local SDK validation errors, not Orchestrator responses. ## Session key failures | Symptom | Cause | Fix | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `No session configured for chain …` | A per-chain signer map is missing a required EVM source or destination chain. | Add that chain's resolved session to `signers.sessions`. | | `Cannot sign a chain-agnostic intent payload with a smart session` | One signature would need to validate on legs from several chains. | Split the operation into per-chain intents. | | `This Smart Session has signing disabled` | `signMessage` or `signTypedData` used a session with `signing.mode: 'disabled'`. | Use account owners or create a session with the required signing capability. | | `Scoped Smart Session signing requires safe ERC-7739 emission` | Direct scoped typed-data signing is not available in SDK 2.16.1. | Use account owners or an unrestricted session only when its risk is acceptable. | | A restricted session rejects an intent as an invalid signature | The route added fee or gas-refund calls that the removed wildcard fallback would have authorized. | Sponsor the intent or explicitly authorize every required call. | | Activation fails after rebuilding session data | The session definition, policy addresses, order, or session index differs from the signed details. | Persist and reuse the exact resolved session and `hashesAndChainIds`. | | A restricted session unexpectedly retains older permissions | Two sessions for the same signer reused a permission ID. | Use `saltMode: 'strict'` for new restricted sessions; enabling it changes the ID, so do not apply it to an existing signed session. | See [Multi-chain sessions](/wallets/session-keys/custom-setup/multi-chain-sessions) and [Restrict a session](/wallets/session-keys/custom-setup/restrict-a-session) for the required shapes. ## Recovery failures | Symptom | Cause | Fix | | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Guardian signing fails in `prepareTransaction`, `signMessage`, or `signTypedData` | Guardians are valid only for recovery UserOperations. | Use `sendUserOperation` with one recovery call. | | Recovery reverts when calls are batched | The recovery validator authorizes one account execution per UserOperation. | Submit one returned call at a time, in order. | | `CredentialAlreadyExists` during passkey recovery | `currentCredentials` omitted an installed passkey. | Rebuild the recovery with the complete current credential set. | | Bundler submission fails or no bundler is configured | Recovery runs through ERC-4337. | Configure a production bundler and retry only the call that did not execute. | | Nexus recovery cannot change owners | The account does not use the same Ownable V0 module in its account and target-owner configuration. | Migrate while the current owner is available, then keep the module address consistent. | Follow [Recover an account](/wallets/custom-signer/recovery/recover-an-account) for the ordering constraints. ## Report a persistent failure Capture: * the SDK version (`2.16.1` for these examples) * the error class, message, `code`, and `traceId` * the account address and chain IDs * the intent ID or UserOperation hash * redacted request parameters and per-operation status Never include private keys, passkey material, API keys, or JWTs.