@rhinestone/sdk/errors. Orchestrator errors include a code, statusCode, and traceId; include the trace ID when contacting support.
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);
}
}
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. |
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. |
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 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. |
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. |
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. |
Report a persistent failure
Capture:- the SDK version (
2.16.1for these examples) - the error class, message,
code, andtraceId - the account address and chain IDs
- the intent ID or UserOperation hash
- redacted request parameters and per-operation status