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

Troubleshooting

Find the cause and the fix for common ensforge symptoms and error messages, each one linked to its page in the error reference.

Find your symptom or error message below. Every error has a stable code, and each code has a page at /docs/reference/errors/<CODE> with causes and fixes. For how to catch and show errors, see Handle errors.

Reads

A read returns null

null means the data is not set, not that the call failed. Check, in order:

  1. The name is spelled as you meant. ensforge normalises names (ENSIP-15), and INVALID_NAME reports names that cannot be normalised.
  2. The name has a resolver and the record exists. Call resolver.get, or pass strict: true to turn null into RESOLVER_NOT_FOUND or RECORD_NOT_FOUND.
  3. The client is on the chain you expect. A Sepolia client does not see mainnet names.

This name resolves off-chain, and CCIP-Read is disabled.

The name keeps its records off-chain (CCIP-Read) and the client was created with ccipRead: false. Remove that option. See CCIP_READ_DISABLED and Look up off-chain names.

An off-chain name fails with a gateway error

The gateway did not answer or returned data ensforge cannot use. A failed request is worth retrying. See GATEWAY_REQUEST_FAILED and GATEWAY_RESPONSE_INVALID.

The primary name does not resolve back to this address.

The address's primary name record names a name whose address record points elsewhere. Set the name's address record to the address, or set another primary name. See PRIMARY_NAME_MISMATCH and Get the name for an address.

The RPC provider is rate limiting requests.

Use a dedicated RPC URL or a fallback transport. See RATE_LIMITED and Configure RPC and gateways.

The RPC provider's eth_getLogs limits make this block range too expensive.

event.get needs wide log ranges. Narrow the block range, use an RPC URL with wider ranges, or read history from an indexer. See LOG_RANGE_TOO_LARGE and Name history.

This action needs an indexer.

You called an indexer.* action on a client without an indexer. Pass indexer to Ensforge.create, and add indexerActions() to the client. See INDEXER_NOT_CONFIGURED and Connect an indexer.

DNS names fail with DNSSEC_PROOF_FAILED

Since the root key rollover in October 2026 the on-chain DNSSEC oracle cannot verify proofs, so DNS name resolution and claims fail on mainnet and Sepolia. ensforge has no client-side workaround. The fix is upstream: ENS must add the new trust anchor to the oracle. See DNSSEC_PROOF_FAILED and Use a DNS name.

Writes

This action needs a wallet client with an account.

The client has no wallet. Pass walletClient to Ensforge.create, or account to the action. See WALLET_NOT_CONFIGURED.

The wallet has no account to sign with.

The wallet client was created without an account and no default account was given. Pass account to Ensforge.create or the write. See ACCOUNT_NOT_FOUND.

The wallet is on chain …, expected ….

The wallet's chain differs from the client's. Switch the wallet or create the client for its chain. See CHAIN_MISMATCH.

... does not own this name.

The signer is not the owner. Send from the owner's account, or check who may change the name. See NOT_OWNER and Who can change a name.

... is missing the roles this change needs.

On ENSv2 names a change needs a role. error.missingRoles names them. See MISSING_ROLES and Roles and permissions.

The resolver does not support this record type.

The name's resolver cannot store that kind of record, for example an older resolver without data records, or a resolver that keeps records off-chain. Point the name at a resolver that supports it. See RESOLVER_PROFILE_UNSUPPORTED and Change the resolver.

The name must be migrated to ENSv2 first.

The write needs the name on ENSv2. Migrate it with migration.migrate. See NAME_REQUIRES_MIGRATION and Move a name to ENSv2.

Timed out waiting for the transaction receipt.

The transaction may still confirm. Check it by hash before sending again. See RECEIPT_TIMEOUT.

The transaction nonce conflicts with another transaction.

Another transaction from the account is pending. Wait for it to confirm, then retry. See NONCE_CONFLICT.

A registration takes more than a minute

That is expected. A registration sends a commitment, waits for the registrar's minimum commitment age on chain time, then registers. With a wallet that does not send atomic bundles, a single name is four to five transactions. Use onStep to show progress. See Register a name and Send a transaction.

A write stopped half-way

Resume it with plan.resume. Do not send it again. See Continue after a failure and PLAN_NOT_FOUND.

Setup

No contract is deployed at the called address.

The client's chain does not match the deployment ensforge uses. Check the chain of your public client. See CONTRACT_NOT_DEPLOYED.

ensforge has no ENS deployment for this chain.

ensforge ships deployments for Ethereum mainnet and Sepolia. For another chain, a fork with a different chain ID or a devnet, pass deployment. See UNKNOWN_CHAIN and Create a client.

A decorator added an action group with a reserved name.

An extension added a group named chain, account, deployment, publicClient, config or extend. Rename the group. See INVALID_ACTION_GROUP and Extend the client.

An unexpected error occurred.

ensforge could not classify the failure. The original error is in error.cause. If it persists, report it at the ensforge issue tracker with the cause. See UNEXPECTED.

Still stuck

Log error.toJSON(). It holds the code, hint, context and docs URL, and is safe to share.

Was this page helpful?