Error Handling

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
  }
}

CofheError structure

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
`PermitNotFound`	No permit found for the given `chainId + account`
`PermitInvalid`	The permit signature is invalid or expired
`DecryptFailed`	Decryption request was rejected by the Threshold Network
`NotConnected`	Attempted an operation before calling `client.connect(...)`

Error handling patterns

Encryption errors

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

try {
  const encrypted = await client
    .encryptInputs([Encryptable.uint128(veryLargeValue)])
    .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.PermitNotFound) {
    // Create a permit and retry
    await client.permits.getOrCreateSelfPermit();
    const plaintext = await client
      .decryptForView(ctHash, FheTypes.Uint32)
      .execute();
  }
}

Distinguishing why a permit is invalid

Since @cofhe/sdk@0.5.0, the decrypt flows call PermitUtils.validate(permit) 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/permits to pre-flight the active permit and route based on the typed reason — this avoids the thrown error path entirely:

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

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

if (!result.valid) {
  switch (result.error) {
    case 'expired':
      await client.permits.getOrCreateSelfPermit(); // create a fresh one
      break;
    case 'not-signed':
      await client.permits.getOrCreateSelfPermit(); // prompt the wallet to sign
      break;
    case 'invalid-schema':
      client.permits.removeActivePermit(); // 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 Permits → Validating permits for the full helper surface.

If you prefer the throwing path: PermitUtils.validate(permit) raises plain Errors with messages Permit is expired / Permit 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.

Introduction

Quick Start

Guides

Hardhat Plugin

Foundry Plugin

Examples

Reference

Catching errors

CofheError structure

Common error codes

Error handling patterns

Encryption errors

Decryption errors

Distinguishing why a permit is invalid

​Catching errors

​CofheError structure

​Common error codes

​Error handling patterns

​Encryption errors

​Decryption errors

​Distinguishing why a permit is invalid

Catching errors

CofheError structure

Common error codes

Error handling patterns

Encryption errors

Decryption errors

Distinguishing why a permit is invalid