Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

How errors work

Learn how ensforge errors are grouped into classes and codes, what each error carries, and how to turn one into a message for users.

When an ENS call fails, ensforge never hands you a raw contract revert or an RPC message. It translates every failure into an ensforge error with a class that says what kind of problem it is, a code that says exactly what happened, and the context you need to fix or report it.

Classes and codes

Each error has two names. The class groups related failures; the code is precise and stable.

ClassExample codesMeans
InvalidInputErrorINVALID_NAME, INVALID_ADDRESSThe input is wrong. Nothing was sent.
NotFoundErrorRESOLVER_NOT_FOUND, RECORD_NOT_FOUNDThe data does not exist.
NameStateErrorNAME_NOT_AVAILABLE, NAME_EXPIREDThe name is in the wrong state for this.
UnauthorizedErrorNOT_OWNER, MISSING_ROLESThe account may not do this.
UserRejectedErrorUSER_REJECTEDThe user declined in their wallet.
NetworkErrorRPC_TIMEOUT, RATE_LIMITEDThe RPC failed. Often worth a retry.
GatewayErrorGATEWAY_REQUEST_FAILEDAn off-chain gateway failed.

There are 19 classes in all. Every code has its own page under Errors, with its causes and how to fix it.

Codes are stable: renaming or removing one is a breaking change, made only in a major release. Branch on codes, never on message text.

What an error carries

Example (Catching an Error)

catch.ts
import { Ensforge, Errors, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());

try {
  await ens.record.getText({ name: "no-such-name-ensforge-docs.eth", key: "url", strict: true });
} catch (error) {
  if (Errors.is(error)) console.log(error.toJSON());
}
Output (trimmed)
{
  name: 'NotFoundError',
  code: 'RESOLVER_NOT_FOUND',
  shortMessage: 'The name no-such-name-ensforge-docs.eth has no resolver.',
  hint: 'Set one with resolver.set.',
  details: [],
  retryable: false,
  context: {
    operation: 'record.getText',
    name: 'no-such-name-ensforge-docs.eth',
    chainId: 1,
    contract: '0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe',
    functionName: 'resolve',
    ...
  },
  docsUrl: 'https://ensforge.com/docs/reference/errors/RESOLVER_NOT_FOUND'
}
FieldWhat it is
name, _tagThe class name, such as "NotFoundError".
codeWhat happened, such as "RESOLVER_NOT_FOUND".
shortMessageOne line for developers.
hintHow to fix it, when ensforge knows.
retryableWhether the same call can succeed if you try again.
contextWhere it happened: the action, name, account, chain, contract and, for writes, the planId and step to resume.
docsUrlThe page for this code.
causeThe original error, such as viem's, when there was one.

error.message combines these into a readable block for logs, ending with the code, the docs link and the SDK version. toJSON() returns a plain object that is safe to send to an error tracker.

Every action declares its errors

Each action lists the errors it can throw, as a type: Actions.record.getText.ErrorType. It is the union of the classes the action documents, plus a few every action can hit (a misconfigured client, a failing RPC, an unexpected revert). Writes add the errors of signing and sending, such as UserRejectedError. Each action's reference page lists them with their codes.

Errors.hasCode narrows an unknown error to the codes you name:

Example (Handling One Code)

has-code.ts
import { Ensforge, Errors, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());

try {
  await ens.record.getAddress({ name: "nick.eth", coin: "btc", strict: true });
} catch (error) {
  if (Errors.hasCode("RECORD_NOT_FOUND", "RESOLVER_NOT_FOUND")(error)) {
    console.log("Nothing to show for", error.context.name);
  } else {
    throw error;
  }
}

Errors.is(value) tells whether a value is an ensforge error at all. It also works when two copies of the SDK are installed, where instanceof would not.

Missing data is not an error

Reads return null for data that is not there: a record that is not set, a name without a resolver, an address without a primary name. Pass strict: true when you want a NotFoundError instead. Invalid input, network and gateway failures are always errors.

Show users a message, not the error

error.message is written for developers. Errors.describe turns any error, from ensforge or not, into a title, message and suggested action that are safe to show users.

Example (Describing an Error for Users)

describe.ts
import { Errors } from "@ensforge/sdk";

declare const error: unknown;
const { title, message, action, severity } = Errors.describe(error);

For the error above, it returns:

Output
{
  title: 'No resolver',
  message: 'no-such-name-ensforge-docs.eth is not set up to hold records yet.',
  action: 'Set a resolver first.',
  code: 'RESOLVER_NOT_FOUND',
  retryable: false,
  severity: 'info'
}
  • severity is "info" for expected outcomes (a declined prompt, a taken name), "warning" for temporary problems worth retrying, and "error" for anything that needs attention.
  • Pass messages to replace the copy for some codes, for example to translate it.
  • Every code has copy, including the HCA codes. An unknown code gets a generic message; describe never throws.

See Handle errors.

Errors in the Effect API

The Effect API throws the same error instances. Each action's error channel is its ErrorType, and the _tag is the class name, so Effect.catchTag("NotFoundError", …) handles one class. See The Effect API.

Was this page helpful?