Error handling

The SDK throws typed error classes. Each one sets a distinct name and carries structured context — there are no numeric error codes. Identify an error by its name (or instanceof), not by parsing its message.

try {
  await client.decryptValue({ transportKeyPair, encryptedValue, contractAddress, signedPermit });
} catch (err) {
  if (err instanceof Error && err.name === 'AclUserDecryptionError') {
    // the user isn't allowed to decrypt this value
  }
}

Every SDK error extends the built-in Error, so err.message, err.name, and err.cause are always available. Domain errors add extra getters (a contract address, a list of handles, an HTTP status) depending on the error.

Categories

Errors fall into three families:

• Validation errors — you passed something malformed (a bad address, an invalid handle). Thrown synchronously, before any network call.
• FHEVM domain errors — the operation is well-formed but not permitted or not possible (Access Control List (ACL) denies decryption, an input proof is invalid).
• Relayer errors — the request to the Relayer failed, timed out, was aborted, or came back rejected.

Validation errors

Thrown when an argument doesn't parse. Catch these to give users immediate feedback without a round-trip.

FHEVM domain errors

Thrown by encrypt, decrypt, and configuration operations.

Relayer errors

Thrown when talking to the Relayer. Response errors carry an HTTP status; fetch errors carry the url, operation, and retry metadata.

Handling patterns

Abort a slow request. Pass an AbortSignal and catch RelayerAbortError:

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 30_000);

try {
  await client.encryptValues({
    contractAddress,
    userAddress,
    values,
    options: { signal: controller.signal },
  });
} catch (err) {
  if (err instanceof Error && err.name === 'RelayerAbortError') {
    // handle cancellation
  }
} finally {
  clearTimeout(timer);
}

Prefer canDecrypt* over catching ACL errors. To decide whether to offer decryption, check permission up front instead of catching AclUserDecryptionError. canDecryptValue is a standalone action, not a client method, so import it and pass the client as the first argument:

import { canDecryptValue } from '@fhevm/sdk/actions/decrypt';

const { allowed } = await canDecryptValue(client, { encryptedValue, contractAddress, signedPermit });
if (allowed) {
  // safe to call decryptValue
}

Inspect the cause. Errors chain via the standard cause property, so you can reach the underlying failure:

catch (err) {
  console.error(err.name, err.message, err.cause);
}

Related

• Decryption → Checking permission — avoid ACL errors entirely.
• Encryption — where EncryptionError / ZkProofError originate.
• Runtime configuration — Sha256VerificationError and asset loading.