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:
- The name is spelled as you meant. ensforge normalises names (ENSIP-15), and
INVALID_NAMEreports names that cannot be normalised. - The name has a resolver and the record exists. Call
resolver.get, or passstrict: trueto turnnullintoRESOLVER_NOT_FOUNDorRECORD_NOT_FOUND. - 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?