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

# Errors

> UmbraError hierarchy: EncryptedDepositError, ClaimUtxoError, RegistrationError etc. with stage fields for precise failure location. Retry guidance per stage.

## Import Path

```typescript theme={null}
import {
  // Staged errors
  EncryptedDepositError,
  EncryptedWithdrawalError,
  RegistrationError,
  ConversionError,
  CreateUtxoError,
  FetchUtxosError,
  ClaimUtxoError,
  QueryError,
  AccountError,
  ComplianceError,
  isEncryptedDepositError,
  isEncryptedWithdrawalError,
  isRegistrationError,
  isConversionError,
  isCreateUtxoError,
  isFetchUtxosError,
  isClaimUtxoError,
  isQueryError,
  isAccountError,
  isComplianceError,

  // Base primitives
  UmbraError,
  CryptographyError,
  InstructionError,
  RpcError,
  TransactionError,
  TransactionSigningError,
  MasterSeedSigningRejectedError,
  isUmbraError,
  isCryptographyError,
  isInstructionError,
  isRpcError,
  isTransactionError,
  isTransactionSigningError,
} from "@umbra-privacy/sdk/errors";
```

***

## Error Hierarchy

```
Error
└── UmbraError
    ├── CryptographyError
    ├── InstructionError
    ├── RpcError
    ├── TransactionError
    │   └── TransactionSigningError
    │       └── MasterSeedSigningRejectedError
    ├── EncryptedDepositError
    ├── EncryptedWithdrawalError
    ├── RegistrationError
    ├── ConversionError
    ├── CreateUtxoError
    ├── FetchUtxosError
    ├── ClaimUtxoError
    ├── QueryError
    ├── AccountError
    └── ComplianceError
```

***

## Staged Errors

Every major SDK operation throws a dedicated staged error. The `stage` field pinpoints exactly where in the pipeline the failure occurred.

***

### EncryptedDepositError

Thrown by `getATAIntoETADirectDepositorFunction`.

```typescript theme={null}
class EncryptedDepositError extends UmbraError {
  readonly stage: EncryptedDepositStage;
}

function isEncryptedDepositError(error: unknown): error is EncryptedDepositError;
```

**Stage values:**

* `"initialization"` - Factory construction failed. Missing required arguments.
* `"validation"` - Invalid mint address, zero amount, or unregistered destination.
* `"mint-fetch"` - Failed to fetch the mint account. Check RPC and mint address.
* `"fee-calculation"` - Token-2022 transfer fee calculation failed. Epoch info issue.
* `"pda-derivation"` - Failed to derive required PDAs.
* `"account-fetch"` - Failed to fetch the destination user or token account.
* `"instruction-build"` - Failed to construct the instruction. Protocol state mismatch.
* `"transaction-build"` - Failed to assemble the transaction. Blockhash fetch failure.
* `"transaction-compile"` - Failed to compile the transaction. Lookup table mismatch.
* `"transaction-sign"` - Wallet rejected signing.
* `"transaction-validate"` - Pre-flight simulation failed. Insufficient funds or account state mismatch.
* `"transaction-send"` - Transaction sent but confirmation timed out. May still have landed.

***

### EncryptedWithdrawalError

Thrown by `getETAIntoATAWithdrawerFunction`.

```typescript theme={null}
class EncryptedWithdrawalError extends UmbraError {
  readonly stage: EncryptedWithdrawalStage;
}

function isEncryptedWithdrawalError(error: unknown): error is EncryptedWithdrawalError;
```

**Stage values:**

* `"initialization"` - Factory construction failed.
* `"validation"` - Zero amount or no encrypted balance exists for this mint.
* `"mint-fetch"` - Failed to fetch the mint account.
* `"pda-derivation"` - Failed to derive required PDAs.
* `"instruction-build"` - Failed to construct the instruction.
* `"transaction-build"` - Blockhash fetch failure.
* `"transaction-compile"` - Failed to compile the transaction.
* `"transaction-sign"` - Wallet rejected signing.
* `"transaction-send"` - Confirmation timed out. May still have landed.

***

### RegistrationError

Thrown by `getUserRegistrationFunction`.

```typescript theme={null}
class RegistrationError extends UmbraError {
  readonly stage: RegistrationStage;
}

function isRegistrationError(error: unknown): error is RegistrationError;
```

**Stage values:**

* `"initialization"` - Factory construction failed.
* `"master-seed-derivation"` - User declined to sign the master seed derivation message.
* `"account-fetch"` - Failed to fetch on-chain account state. RPC connectivity issue.
* `"key-derivation"` - Cryptographic key derivation from master seed failed.
* `"zk-proof-generation"` - Groth16 proof generation failed (anonymous step only).
* `"pda-derivation"` - Failed to derive required PDAs.
* `"instruction-build"` - Failed to construct an instruction.
* `"transaction-build"` - Blockhash fetch failure.
* `"transaction-compile"` - Failed to compile the transaction.
* `"transaction-sign"` - Wallet rejected signing.
* `"transaction-validate"` - Pre-flight simulation failed.
* `"transaction-send"` - Confirmation timed out. May still have landed.

***

### ConversionError

Thrown by `getNetworkEncryptionToSharedEncryptionConverterFunction` and `getMintEncryptionKeyRotatorFunction`.

```typescript theme={null}
class ConversionError extends UmbraError {
  readonly stage: ConversionStage;
}

function isConversionError(error: unknown): error is ConversionError;
```

**Stage values:**

* `"initialization"` - Factory construction failed.
* `"account-fetch"` - Failed to fetch token account state.
* `"pda-derivation"` - Failed to derive required PDAs.
* `"instruction-build"` - Failed to construct the conversion instruction.
* `"transaction-build"` - Blockhash fetch or transaction assembly failed.
* `"transaction-compile"` - Failed to compile the transaction.
* `"transaction-sign"` - Wallet rejected a per-mint transaction.
* `"transaction-validate"` - Pre-flight simulation failed.
* `"transaction-send"` - Confirmation timed out. Already-converted mints remain on-chain.

***

### CreateUtxoError

Thrown by all four Stealth Pool Note creator factory functions in `@umbra-privacy/sdk/deposit`.

```typescript theme={null}
class CreateUtxoError extends UmbraError {
  readonly stage: CreateUtxoStage;
}

function isCreateUtxoError(error: unknown): error is CreateUtxoError;
```

**Stage values:**

* `"initialization"` - Factory construction failed.
* `"validation"` - Invalid recipient, mint, or amount.
* `"account-fetch"` - Failed to fetch the recipient's on-chain account.
* `"mint-fetch"` - Failed to fetch mint account data.
* `"fee-calculation"` - Token-2022 transfer fee calculation failed.
* `"key-derivation"` - Key derivation from master seed failed.
* `"zk-proof-generation"` - Groth16 proof generation failed.
* `"pda-derivation"` - Failed to derive required PDAs.
* `"instruction-build"` - Failed to construct the instruction.
* `"transaction-build"` - Blockhash fetch or transaction assembly failed.
* `"transaction-compile"` - Failed to compile the transaction.
* `"transaction-sign"` - Wallet rejected signing.
* `"transaction-validate"` - Pre-flight simulation failed.
* `"transaction-send"` - Confirmation timed out. May still have landed - check before retrying.

***

### FetchUtxosError

Thrown by `getBurnableStealthPoolNoteScannerFunction` in `@umbra-privacy/sdk/burn`.

```typescript theme={null}
class FetchUtxosError extends UmbraError {
  readonly stage: FetchUtxosStage;
}

function isFetchUtxosError(error: unknown): error is FetchUtxosError;
```

**Stage values:**

* `"initialization"` — factory construction failed. `indexerApiEndpoint` not configured.
* `"validation"` — invalid scanner-level input.
* `"key-derivation"` — X25519 private key derivation from master seed failed.
* `"indexer-fetch"` — indexer HTTP call failed (unreachable, rate-limited, or error response).
* `"proof-fetch"` — Merkle proof HTTP call failed (from the burner's per-batch proof fetch).
* `"proof-enrichment"` — `enrichWithMerkleProof` failed to attach a proof entry to a scanned note (missing proof for the note's insertion index).

***

### ClaimUtxoError

Thrown by all three burner factory functions in `@umbra-privacy/sdk/burn`.

```typescript theme={null}
class ClaimUtxoError extends UmbraError {
  readonly stage: ClaimUtxoStage;
}

function isClaimUtxoError(error: unknown): error is ClaimUtxoError;
```

**Stage values:**

* `"initialization"` - Factory construction failed.
* `"validation"` — invalid Stealth Pool Note data or parameters.
* `"key-derivation"` - Key derivation from master seed failed.
* `"zk-proof-generation"` - Groth16 proof generation failed.
* `"pda-derivation"` - Failed to derive required PDAs.
* `"instruction-build"` - Failed to construct the instruction.
* `"transaction-build"` - Blockhash fetch or transaction assembly failed.
* `"transaction-compile"` - Failed to compile the transaction.
* `"transaction-sign"` - Wallet rejected signing.
* `"transaction-validate"` — pre-flight simulation failed. Often indicates a stale Merkle proof — the burner refetches the proof on a retry, so just re-run the burn.
* `"transaction-send"` - Confirmation timed out. Verify on-chain before retrying - the nullifier may have been burned.

***

### QueryError

Thrown by `getUserAccountQuerierFunction` and `getEncryptedBalanceQuerierFunction`.

```typescript theme={null}
class QueryError extends UmbraError {
  readonly stage: QueryStage;
}

function isQueryError(error: unknown): error is QueryError;
```

**Stage values:**

* `"initialization"` — factory-level validation failed.
* `"pda-derivation"` — PDA address generation failed.
* `"account-fetch"` — RPC fetch failed (node unreachable or returned an error).
* `"account-decode"` — on-chain account data could not be decoded. Unexpected on-chain state.
* `"key-derivation"` — X25519 key derivation failed (encrypted balance query only).
* `"decryption"` — Rescue cipher decryption failed (encrypted balance query only).

***

### AccountError

Thrown by every factory in `@umbra-privacy/sdk/account` — staged-token recoverers (`getStagedSolRecovererFunction`, `getStagedSplRecovererFunction`), key rotators (`getUserEncryptionKeyRotatorFunction`, `getMasterViewingKeyRotatorFunction`, `getMintEncryptionKeyRotatorFunction`), and entropy-seed rotators (`getUserEntropySeedRotatorFunction`, `getTokenEntropySeedRotatorFunction`).

```typescript theme={null}
class AccountError extends UmbraError {
  readonly stage: AccountStage;
}

function isAccountError(error: unknown): error is AccountError;
```

**Stage values:** `"initialization"` | `"validation"` | `"account-fetch"` | `"account-decode"` | `"key-derivation"` | `"zk-proof-generation"` | `"pda-derivation"` | `"instruction-build"` | `"transaction-build"` | `"transaction-compile"` | `"transaction-sign"` | `"transaction-validate"` | `"transaction-send"`.

`"zk-proof-generation"` is only reachable from `getMasterViewingKeyRotatorFunction` (the only account operation that runs a ZK proof).

***

### ComplianceError

Thrown by every factory in `@umbra-privacy/sdk/compliance` — grant issuer / revoker / queriers / re-encryptors.

```typescript theme={null}
class ComplianceError extends UmbraError {
  readonly stage: ComplianceStage;
}

function isComplianceError(error: unknown): error is ComplianceError;
```

**Stage values:** `"initialization"` | `"validation"` | `"key-derivation"` | `"pda-derivation"` | `"account-fetch"` | `"account-decode"` | `"decryption"` | `"reencryption"` | `"instruction-build"` | `"transaction-build"` | `"transaction-compile"` | `"transaction-sign"` | `"transaction-validate"` | `"transaction-send"`.

`"decryption"` / `"reencryption"` are only reachable from the re-encryptor factories (`getSharedCiphertextReencryptorForUserGrantFunction`, etc.). The grant lifecycle factories (issue / revoke) never hit those stages.

***

## Base Error Primitives

These are the underlying error types. All staged errors extend `UmbraError`.

***

### UmbraError

Base class for all SDK errors.

```typescript theme={null}
class UmbraError extends Error {
  constructor(
    message: string,
    options?: {
      code?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly code: string;          // Machine-readable code. Defaults to "UMBRA_ERROR".
  readonly context?: Record<string, unknown>;
  override readonly cause?: unknown;
}

function isUmbraError(error: unknown): error is UmbraError;
```

***

### CryptographyError

Thrown when a cryptographic operation fails - most commonly ZK proof generation or Rescue cipher encryption/decryption.

```typescript theme={null}
class CryptographyError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      operation?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly operation?: string;    // Name of the failed operation, e.g. "groth16-prove".
}

function isCryptographyError(error: unknown): error is CryptographyError;
```

***

### InstructionError

Thrown when instruction construction fails - typically a protocol state mismatch or missing on-chain account.

```typescript theme={null}
class InstructionError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      instructionName?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly instructionName?: string;    // Name of the instruction that failed to build.
}

function isInstructionError(error: unknown): error is InstructionError;
```

***

### RpcError

Thrown when an RPC or indexer HTTP call fails.

```typescript theme={null}
class RpcError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      endpoint?: string;
      statusCode?: number;
      rpcErrorCode?: number;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly endpoint?: string;       // The URL that was called.
  readonly statusCode?: number;     // HTTP status code (e.g. 429 for rate limit, 503 for unavailable).
  readonly rpcErrorCode?: number;   // JSON-RPC error code from the node.
}

function isRpcError(error: unknown): error is RpcError;
```

***

### TransactionError

Thrown when a transaction fails on-chain (simulation rejection or network rejection).

```typescript theme={null}
class TransactionError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      signature?: string;
      simulationLogs?: string[];
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly signature?: string;          // Base58 tx signature. Present even on failure - tx may have landed.
  readonly simulationLogs?: string[]    // Program log output from pre-flight simulation.
}

function isTransactionError(error: unknown): error is TransactionError;
```

***

### TransactionSigningError

Thrown when a wallet rejects a transaction signing request. Extends `TransactionError`.

```typescript theme={null}
class TransactionSigningError extends TransactionError {
  constructor(
    message: string,
    options?: {
      code?: string;
      wasRejected?: boolean;
      signerAddress?: string;
      signature?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly wasRejected: boolean;      // true = user explicitly cancelled; false = wallet error.
  readonly signerAddress?: string;    // Address of the wallet that rejected.
}

function isTransactionSigningError(error: unknown): error is TransactionSigningError;
```

***

### MasterSeedSigningRejectedError

Thrown when the user declines to sign the master seed derivation message. Extends `TransactionSigningError`. Always has `wasRejected: true`. Error code: `"MASTER_SEED_SIGNING_REJECTED"`.

This surfaces during the first operation that needs key material in a session - typically `register()`, or `getUmbraClient()` in non-deferred mode.

```typescript theme={null}
class MasterSeedSigningRejectedError extends TransactionSigningError {
  constructor(
    message?: string,
    options?: {
      signerAddress?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );
}
```

***

## Retry Strategy

* `"transaction-sign"` / `MasterSeedSigningRejectedError` - **Do not retry.** User cancelled. Never auto-retry a wallet prompt rejection.
* `"transaction-send"` with a `signature` present - **Check first.** The transaction may have landed. Verify on-chain before submitting again to avoid double submissions.
* `"transaction-validate"` - **Fix inputs first.** Pre-flight simulation failed. Diagnose the root cause before retrying.
* `"transaction-validate"` for burns — may indicate a stale Merkle proof. Re-run the burner; it fetches a fresh per-batch proof on each attempt.
* `isRpcError` - **Safe to retry with exponential backoff.** Transient network issue.
* All other stages - **Safe to retry with exponential backoff.**