Known limitations
Check the known limits of ensforge 1.0 and of ENS itself, grouped by topic, with what each one means and what to do about it.
These are the places where ensforge 1.0, or the ENS contracts and services it uses, behave in a way you might not expect. Each entry says what happens and what to do. Most come from how the ENS protocol works and are not bugs.
Records and resolvers
Older public resolvers show as custom
resolver.get reports some older ENS public resolvers, such as the 2020 one, as
kind: "custom" with authorization: "unknown". They are not in the deployment's list of known
resolvers, so ensforge cannot prove how they decide who may write.
What to do: reading and writing records still works, except kinds of record the resolver
lacks: the 2020 public resolver has no data records and cannot clear. To use a resolver
ensforge recognises, pass resolver: "default" to record.set with the records to keep. It writes
them to the current public resolver and points the name at it. Records you do not pass are not
copied.
Frozen resolvers cannot change records
Names on three old public resolvers, tied to the registry ENS replaced in 2020, cannot change their
records. record.set fails before sending and suggests a new resolver.
What to do: pass resolver to record.set to write the records to a new resolver and point the
name at it in one step.
The ENSv2 public resolver only serves Name Wrapper names
resolver: "default" works for ENSv1 names only. On ENSv2 names it fails with
UNSUPPORTED_PROTOCOL, because the ENSv2 public resolver
only accepts names the Name Wrapper knows.
What to do: give the name its own resolver with resolver.create.
Clearing records on a PermissionedResolver shows its default record
record.set({ clear: true }) on an ENSv2 PermissionedResolver links the name to the resolver's
default record. Until new records are written, the name reads that default record, which is empty
unless someone set it.
What to do: write the new records in the same record.set call as clear. ensforge clears
first and writes the new records in the same transaction.
Shared resolvers share record access
On a PermissionedResolver used by several names, permission.setRecordAccess lets the grantee
edit those records on every name that uses the resolver.
What to do: keep one resolver per name, as ensforge does by default. Share a resolver only with accounts you trust for every name on it.
Predicted resolver addresses assume the signer sends
resolver.create predicts the new resolver's address from the account that sends the deploy call.
If a relayer or a bundler sends it instead, the resolver lands at another address.
What to do: send resolver.create from the account itself, or read the address from the
receipt.
Some coins are not supported
EOS (coin type 194) and other coins whose encoders were removed upstream fail with
INVALID_COIN_TYPE or
INVALID_ADDRESS.
What to do: nothing in ensforge; these coins cannot be encoded.
XRP addresses can be stored two ways
An XRP X-address and the r-address of the same account encode to different bytes, so the same account can be stored in two forms.
What to do: pick one form for your app and store addresses in it.
The default IPFS gateway is rate limited
Avatars and website links on IPFS go through https://ipfs.io by default, which answers HTTP 429
under load.
What to do: set your own gateway with Ensforge.create({ gateways: { ipfs: "…" } }). See
Configure RPC and gateways.
Writes and plans
RPCs without eth_simulateV1 cannot simulate dependent calls
ensforge simulates a step's calls in sequence with eth_simulateV1. On RPCs without it, each call
is simulated alone, so a call that depends on an earlier one in the same step can fail in
simulation although sending would succeed.
What to do: use an RPC that supports eth_simulateV1, or send that write with
simulate: false.
Plans are kept in memory by default
The default plan storage loses plans on a page reload, and an aborted write rejects with the abort reason instead of an error carrying the plan id.
What to do: create the client with storage: Plan.localStorage() or your own Plan.Storage.
Find the id of an aborted plan with plan.list. See
Continue after a failure.
Wallets differ in bundle size and resuming
maxBundleCalls defaults to 10, MetaMask's limit. Resuming a bundle sent through EIP-5792 asks the
wallet that sent it, since only that wallet knows the bundle.
What to do: lower maxBundleCalls for wallets with a smaller limit, and resume with the same
wallet.
Registration
Registering takes at least a minute
registration.register commits, waits the registrar's minimum commitment age on chain time (60
seconds on the networks tested), then registers. With a payment approval, a resolver and a primary
name, one name takes four to five transactions.
What to do: show progress with onStep. A wallet that supports atomic batches bundles each
step's calls. commit and a later register with the same secret split the flow across sessions.
Contracts that reject ERC-1155 tokens cannot own ENSv2 names
ENSv2 sends the new name to its owner as an ERC-1155 token. If owner is a contract that does not
accept ERC-1155 tokens, the register step reverts after the commit was sent.
What to do: register to an account, or to a contract that implements onERC1155Received.
Subnames and registries
An ENSv2 subname's owner cannot be changed from its parent
subname.update({ owner }) on an ENSv2 subname fails with
UNSUPPORTED_PROTOCOL: only the token holder can transfer
it.
What to do: the subname's owner calls name.transfer, or the parent removes the subname and
creates it again.
Subnames created without an expiry cannot get one later
ENSv2 subnames never expire by default, and an expiry can only be extended, not added.
subname.update({ expiry }) on such a subname fails with
INVALID_EXPIRY.
What to do: pass expiry to subname.create when subnames should lapse.
Some ENSv2 registries cannot be upgraded
Registries created on mainnet before 17 November 2026 run an implementation that the latest one
does not accept. registry.get reports blocker: "not-approved", and registry.upgrade fails
with UPGRADE_NOT_APPROVED.
What to do: nothing until ENS approves an upgrade path. These registries keep working.
Permissions
.eth owners cannot delegate renewal
role.grant({ roles: ["renew"] }) on a .eth name fails with
CANNOT_GRANT_ROLES: the .eth registrar gives owners no
right to grant it.
What to do: nothing is needed. Anyone can renew a .eth name with registration.renew.
DNS names
DNSSEC proofs do not verify at the moment
Since the DNS root changed its signing key in October 2026, the ENS DNSSEC oracle no longer accepts
any proof, on mainnet and Sepolia. dns.getStatus reports proof-invalid, and dns.claim fails
with DNSSEC_PROOF_FAILED. Lookups of DNS names that
resolve through a proof, because they have no resolver of their own in ENS (such as
ens.domains), fail the same way.
What to do: nothing on the client side. This needs ENS to add the new key to its oracle.
dns.claim cannot set an address
ENS public resolvers refuse the address the DNS registrar would set while claiming.
What to do: claim with resolver only, then set records with record.set.
DNS names are imported into ENSv1
There is no ENSv2 way to claim a second-level DNS name yet. dns.claim imports it into ENSv1, and
ENSv2 resolves it from there.
What to do: nothing; lookups work as usual.
DNS reads are not verified
dns.getProof and dns.getOffchainResolver return what the gateway sends without verifying it,
and ignore blockNumber and blockTag. dns.getStatus does verify the proof.
What to do: use dns.getStatus when the answer must be trusted.
Moving names to ENSv2
Migration needs records and subnames listed without an indexer
Without an indexer, migration.migrate cannot discover every record and subname of a name. With
one, it finds them itself, up to 500 subnames across all levels.
What to do: create the client with an indexer, or pass the records and subnames yourself.
See Move a name to ENSv2.
Subname records stay where they are
Migrated subnames keep their records on their ENSv1 resolvers, as in the ENS app. Lookups keep working: the subnames still point at those resolvers.
What to do: nothing for lookups. To give a subname its own ENSv2 resolver, read its records
with record.get, then create a resolver with them with resolver.create({ name, records }).
Public keys and DNS records are not copied
ENSv2 PermissionedResolvers have no public key or DNS record types, so migration cannot copy them.
What to do: keep a copy before migrating if you need them.
A name in its grace period migrates as the signer's
The registrar hides who held an expired name. With renew, ensforge assumes the signer is the
registrant, and checks the transfer again after renewing.
What to do: migrate names in grace from the account that held them.
Events and history
Event history over RPC is bounded
event.get needs a block range. Free RPC plans that limit eth_getLogs to a few blocks reach the
request budget quickly and fail with
LOG_RANGE_TOO_LARGE. Some transfers are not scanned:
Name Wrapper token transfers, and .eth and root registry transfers beyond 5,000 blocks for
anyone but the current owner.
What to do: use indexer.getHistory or indexer.getEvents for full history. See
Name history.
Indexers
Indexers disagree on some fields
bigname and Goldsky answer some fields differently: a name's registration date, the format of registration ids, and which fields and counts they fill.
What to do: compare answers from one indexer only. Every answer says which indexer gave it in
indexer.
Snapshots and finality need bigname
at and finality exist only on name, records, registry and resolver reads, and only bigname
supports them. Goldsky fails with INDEXER_UNSUPPORTED.
bigname answers INDEXER_BEHIND when it no longer keeps the
requested snapshot.
What to do: use bigname for snapshot reads, and retry without at when it is behind.
Basenames come from Goldsky
bigname does not index Basenames yet, so it reports INDEXER_UNSUPPORTED for them.
What to do: use fallback([bigname(), goldsky()]); Basenames are then served by Goldsky.
A missing indexer route looks like a missing name
A server that lacks a route answers like it does for an unknown name, so the call fails with
INDEXER_NOT_FOUND instead of INDEXER_UNSUPPORTED.
What to do: check the indexer's version when a list you expect is not found.
Custom indexer answers are checked shallowly
defineIndexer checks that answers are objects and that pages have an items array. Field types
are trusted to your adapter's TypeScript types.
What to do: validate your source's data in the adapter.
bigname misses some names under new registries
Names under a subregistry set at registration on ENSv2 registries created since 17 November 2026 are missing from bigname. Reads from the chain are not affected.
What to do: read such names with chain actions until bigname handles them.
Indexed expiry of ENSv1 names
For ENSv1 names not yet moved to ENSv2, bigname reports the expiry of the ENSv2 reservation, not of
the .eth registration.
What to do: use name.get for the expiry of an ENSv1 name.
Smart accounts (HCA)
@ensforge/hca is experimental. See HCA.
Bundlers and Rhinestone are not proven in production
The bundler route has not been tested against a production bundler in safe mode. The rhinestone
executor needs a Rhinestone SDK that supports standalone ENS HCAs, and fails with
HCA_SDK_UNSUPPORTED with one that does not.
What to do: test these routes on Sepolia before relying on them.
Writes through an HCA need the HCA's authority
Through via: hca() the HCA sends the calls. Registration, migration and hca.execute work. Other
writes, such as records, roles and transfers, succeed only where the HCA holds the needed
permissions, and fail at simulation otherwise. L2 primary names cannot be sent through an HCA.
What to do: use hca() for registration and migration, and the owner's wallet for other writes.
Migrating wrapped names leaves a Name Wrapper approval
Wrapped names need the HCA approved as an operator on the Name Wrapper. The plan warns with
HCA_WRAPPER_APPROVAL, and the approval stays after migration.
What to do: revoke it afterwards with approval.setOperator.
A session on a not-yet-deployed account is not confirmed to work before deployment
The owner can sign a session for the predicted HCA address before the account is deployed. Whether the account accepts that session on its first use, before it is deployed, is not confirmed.
What to do: deploy the HCA with hca.deploy before the session runs.
Session approvals use Rhinestone's signing format
Session approvals are signed as Rhinestone Smart Session data, which an account with Smart Sessions installed could also accept.
What to do: nothing yet. ENS plans its own signing format for sessions, and ensforge switches to it once ENS deploys it.
React server rendering
Streamed reads need a serializer that streams promises
dehydrate(registry, { streaming: true }) puts a real Promise on every read that is still loading.
TanStack Start's serializer (seroval) sends it, and React Server Components do too. React Router's
turbo-stream should, by its documented behaviour, but this is not verified. A serializer that
writes plain JSON drops the Promise without an error, and the browser then fetches the read itself.
What to do: stream only through a serializer that supports promises, or await prefetch and
call dehydrate(registry) without streaming.
Errors
Route errors are outside a write's error type
A write sent through a via route can fail with the route package's own errors, such as
HcaError, which are not part of the action's ErrorType.
What to do: check for HcaError too when you send through hca(). See
How errors work.
Was this page helpful?