Skip to content

Errors ​

Every error the SDK throws is an ArmadaError with a stable code. Match on the code — with isArmadaError — not on the class or the message:

ts
import { isArmadaError } from '@armada/sdk';

try {
  await wallet.sync();
} catch (err) {
  if (isArmadaError(err, 'RPC') && err.transport) {
    // The node couldn't be reached: retry later, or on another RPC.
  } else if (isArmadaError(err)) {
    console.error(err.code, err.message);
  } else {
    throw err; // not the SDK's
  }
}

isArmadaError(err) is true for any SDK error, and isArmadaError(err, code) for one with that code. It works on the code, so it also recognises an error from another copy of the SDK — instanceof is false when the SDK is loaded twice, for example once as an ES module and once as CommonJS. An error from another library with a code field (ethers' NETWORK_ERROR, say) isn't an SDK error. The full list is exported as ERROR_CODES, with its type ErrorCode.

Errors keep their class and code when they cross the prover's worker boundary.

Codes ​

CodeClassThrown whenWhat to do
ABORTEDAbortedErrorA proof (or its artifact download) was cancelled through its AbortSignal.Nothing; the caller cancelled it.
ARTIFACT_FETCHArtifactFetchErrorA proving-artifact download failed or timed out. status is the HTTP status, when there was one.Retry; check the artifact URL.
ARTIFACT_INTEGRITYArtifactIntegrityErrorDownloaded artifacts don't match the manifest's digests.Don't use them; check the artifact host.
FEE_QUOTE_EXPIREDFeeQuoteExpiredErrorassertPreflight: the fee quote expires before the spend could land.Get a fresh quote and re-plan.
INDEXER_HTTPIndexerHttpErrorThe quick-sync indexer answered with a non-OK status (status). Sync falls back to RPC on its own, so you'll see this in telemetry, not thrown.Check the indexer URL.
INSTANCE_CLOSEDInstanceClosedErrorA call after sdk.close() or wallet.dispose(), or a sync or proof they cut short; a closed storage adapter.Nothing, if you closed it; otherwise create a new instance.
INSUFFICIENT_BALANCEInsufficientBalanceErrorNo single tree's spendable notes cover the spend and its fee.Spend less, wait for pending notes, or consolidate.
INTERNALInternalErrorAn SDK invariant broke: a bug, or state the SDK didn't write (a foreign storage record, artifacts the prover can't use).Report it.
INVALID_CONFIGInvalidConfigErrorA malformed config at createArmadaSdk, or an RPC that doesn't serve the configured chain or pool.Fix the config.
INVALID_KEY_MATERIALInvalidKeyMaterialErrorA key failed validation: malformed or truncated, a zero scalar, an off-curve point.Check the key's source.
INVALID_REQUESTInvalidRequestErrorA request the SDK won't act on: a bad amount, a cross-chain unshield the pool would reject, a plan with no merkle proofs.Fix the request.
NO_SPEND_CAPABILITYNoSpendCapabilityErrorA spend-path call on a view-only wallet.Attach a signer.
NOTE_ALREADY_SPENTNoteAlreadySpentErrorassertPreflight: an input note is already spent on-chain.Sync, then re-plan.
NOTHING_TO_CONSOLIDATENothingToConsolidateErrorconsolidate found nothing worth merging.Nothing to do.
POSITION_GAPPositionGapErrorA merkle tree received a leaf out of order. Sync recovers from it by rescanning.Nothing, unless it persists.
PROOF_EXPIREDProofExpiredErrorA ProofHandle was used past its expiresAt.Re-plan and re-prove.
PROOF_HANDLE_INVALIDATEDProofHandleInvalidatedErrorA ProofHandle was used after invalidate().Re-plan and re-prove.
PROOF_VERIFICATIONProofVerificationErrorA fresh proof failed its local check, so it would revert on-chain.Report it.
PROVER_WORKERProverWorkerErrorThe prover worker crashed, failed to load, or was terminated; the prover was closed; or the worker reported an error with no SDK code.Retry: the next proof starts a fresh worker.
QUICK_SYNC_SCHEMAQuickSyncSchemaErrorThe indexer served data that doesn't match its schema or its leaf hashes. Sync falls back to RPC on its own.Check the indexer.
ROOT_MISMATCHRootMismatchErrorA synced tree doesn't match the pool's on-chain root, or a plan's root is no longer accepted.Retry the sync (the RPC may have returned incomplete logs); re-plan a spend.
RPCRpcErrorAn RPC call failed. method names it, cause is the provider's error, and transport is true when the node couldn't be reached.Retry later or on another RPC when transport is true; otherwise check the node.
SIGNER_CONTRACT_VIOLATIONSignerContractViolationErrorA SpendSigner broke its contract: the wrong key, a bad or missing signature.Fix the signer.
STORAGE_CONFLICTStorageConflictErrorAnother live instance holds the storage (another tab or process), or an open adapter was asked to rebind to another deployment.Close the other instance first.
STORAGE_UNAVAILABLEStorageUnavailableErrorThe browser has no Web Locks API (an insecure context, or a very old browser), so the IndexedDB adapter won't open unlocked.Serve the app over HTTPS, or use a current browser.
TOO_FRAGMENTEDTooFragmentedErrorA spend needs more input notes than one batch of proofs can hold.Consolidate first.
UNSUPPORTED_CIRCUIT_SHAPEUnsupportedCircuitShapeErrorA plan needs a circuit shape the deployment has no artifacts for.Consolidate, or register the shape.