Error Handling

Handle errors from @cofhe/sdk operations using typed CofheError objects

All SDK operations return values directly and throw typed CofheError objects on failure. This replaces the Result wrapper pattern used by cofhejs.

Catching errors

import { isCofheError, CofheErrorCode, Encryptable } from '@cofhe/sdk';

try {
  const [encrypted] = await client
    .encryptInputs([Encryptable.uint32(42n)])
    .execute();
} catch (err) {
  if (isCofheError(err)) {
    console.error(err.code);    // CofheErrorCode enum value
    console.error(err.message); // human-readable description
  }
}

What a CofheError carries

Every CofheError has:

• code: a CofheErrorCode enum value identifying the error type
• message: a human-readable description of what went wrong

Use isCofheError(err) to check if a caught error is a CofheError.

Common error codes

Error code	When it occurs
ZkPackFailed	encryptInputs exceeded the 2048-bit plaintext limit
ConsumingContractUninitialized	execute() was called without setConsumingContract(...)
ACPNotFound	No ACP found for the given chainId + account
ACPInvalid	The ACP signature is invalid
ACPExpired	The ACP is past its expiration
ACPRevoked	The issuer revoked this ACP
ACPDenied	The ACP does not cover the requested handle
ACPRequired	The flow needs an ACP and none was supplied
DecryptFailed	Decryption request was rejected by the Threshold Network
NotConnected	Attempted an operation before calling client.connect(...)

The Permit* codes are gone. PermitNotFound and PermitInvalid are now ACPNotFound and ACPInvalid. The set also expanded: expiry, revocation, and scope denial each have their own code, so you no longer have to infer which one applied from the message.

Error handling patterns

Encryption errors

import { isCofheError, CofheErrorCode, Encryptable } from '@cofhe/sdk';

try {
  const encrypted = await client
    .encryptInputs([Encryptable.uint128(veryLargeValue)])
    .setConsumingContract(contractAddress)
    .execute();
} catch (err) {
  if (isCofheError(err) && err.code === CofheErrorCode.ZkPackFailed) {
    console.error('Input too large, split into multiple calls');
  }
}

Decryption errors

import { isCofheError, CofheErrorCode, FheTypes } from '@cofhe/sdk';

try {
  const plaintext = await client
    .decryptForView(ctHash, FheTypes.Uint32)
    .execute();
} catch (err) {
  if (isCofheError(err) && err.code === CofheErrorCode.ACPNotFound) {
    // Create an ACP and retry
    await client.acp.getOrCreateSelfACP();
    const plaintext = await client
      .decryptForView(ctHash, FheTypes.Uint32)
      .execute();
  }
}

Distinguishing why an ACP is invalid

The decrypt flows call ACPUtils.validate(acp) internally before talking to the Threshold Network. That helper enforces schema + signed + not-expired all at once, so when it fails the recovery path depends on which check tripped.

Use the non-throwing ValidationUtils.isValid helper from @cofhe/sdk/acps to pre-flight the active ACP and route based on the typed reason, which avoids the thrown error path entirely:

import { FheTypes } from '@cofhe/sdk';
import { ValidationUtils } from '@cofhe/sdk/acps';

const active = client.acp.getActiveACP();
const result = active
  ? ValidationUtils.isValid(active)
  : { valid: false, error: 'not-signed' as const };

if (!result.valid) {
  switch (result.error) {
    case 'expired':
      await client.acp.getOrCreateSelfACP(); // create a fresh one
      break;
    case 'not-signed':
      await client.acp.getOrCreateSelfACP(); // prompt the wallet to sign
      break;
    case 'invalid-schema':
      client.acp.removeActiveACP(); // stored payload is malformed
      break;
  }
}

const plaintext = await client
  .decryptForView(ctHash, FheTypes.Uint32)
  .execute();

ValidationResult.error is the typed union 'invalid-schema' | 'expired' | 'not-signed' | null. See validating ACPs for the full helper surface.

If you prefer the throwing path: ACPUtils.validate(acp) raises plain Errors with messages ACP is expired / ACP is not signed (or a Zod schema error). These are not wrapped in CofheError, so use err.message rather than an error code to branch.