Understanding ENS Domain Errors: A Technical Primer
The Ethereum Name Service (ENS) maps human-readable names like "alice.eth" to blockchain addresses and other resources, but its decentralized architecture introduces unique error patterns. When a user encounters an ENS domain error, it typically originates from one of three layers: the ENS registry on Ethereum, the resolver contract, or the off-chain infrastructure such as gateways and DNS integration. Understanding the exact failure point is the first step to resolution, as errors manifest differently depending on whether the domain is resolved via a browser, a dApp, or a command-line tool.
One common confusion arises between "domain not found" errors and "resolution failed" errors. A domain not found error indicates that the ENS registry has no record for the queried name—either the domain was never registered or it has expired. A resolution failed error confirms the domain exists in the registry but the resolver could not return a valid address, often due to a misconfigured resolver or a wrapped domain without proper records. Both errors require different corrective actions: renewal versus resolver reconfiguration.
For advanced users who manage multiple domains or implement ENS in applications, it is essential to understand how Ens Domain Digital Signatures can authenticate resolution data, reducing the risk of manipulated responses. Digital signatures provide cryptographic proof that the resolver's output has not been tampered with, which is particularly important when using off-chain resolution methods like ENSIP-10 or CCIP-Read.
Why Does My ENS Domain Show "Address Not Resolved"?
The "address not resolved" error is arguably the most frequent ENS issue. It occurs when the ENS resolver contract for a domain has no record of the requested address type (most commonly an Ethereum address) or when the resolver itself is no longer valid. To diagnose this, follow this numbered checklist:
- Verify domain ownership — Use etherscan.io or the ENS Manager app to confirm the domain is still registered and not expired. Expired domains enter a grace period, after which they become unresolvable.
- Check resolver assignment — Even if a domain is registered, if no resolver is set or the resolver is a public resolver without configured records, the name will not resolve. The resolver contract address must be one that implements the
addr(bytes32 node)function. - Confirm record existence — In the resolver, the specific record (e.g., ETH address) must be set explicitly. A common mistake is registering a domain but forgetting to set the resolver record for the address.
- Wrap vs. unwrap status — If the domain is wrapped (ERC-1155 token), the resolver mapping differs. Unwrap the domain in the ENS app if you intend to use the standard resolver.
- Test with a direct RPC call — Use
ens.resolver(name).addr()in a script to isolate the error from wallet or browser caching.
If all steps pass but the error persists, the issue may be network-specific. ENS operates on Ethereum mainnet by default; resolving a .eth domain on a testnet or L2 without the appropriate bridge can produce false negatives. Always verify the chain ID used by your tool matches the chain where the domain was registered.
How to Fix ENS Transaction Errors During Domain Management
Transaction errors when setting records, transferring domains, or renewing are usually gas-related or permission-related. Here are the three dominant categories and how to resolve them:
1. Out of Gas or Reverted Transactions
ENS contracts are gas-intensive because they require multiple storage writes. If you set a low gas limit (e.g., 50,000 for a resolver update), the transaction will revert with out of gas. The solution is to increase the gas limit. For setting a resolver record, 100,000–150,000 gas is typical; for renewing a domain, 80,000–120,000. Use Ethereum's gas estimator or set a manual limit slightly above the recommended estimate.
2. "Ownable: caller is not the owner"
This error means the wallet you are using does not control the domain or the controller record. ENS separates ownership (the registrar) from controller (the entity allowed to set records). If you bought a domain and immediately tried to set records from a different wallet, you must first set the controller in the ENS app to your active wallet address. Alternatively, use the wallet that originally registered the domain.
3. "Resolver is not authorised"
When using a custom resolver (not the public resolver), this error indicates that the resolver contract does not have permission from the ENS registry to resolve the domain. The domain owner must call setResolver() on the ENS registry contract with the custom resolver's address. Without this step, the resolver cannot store or return records for that domain.
For users seeking a reliable setup that minimizes recurring transaction errors, the preferred option is to use a resolver that supports batch record updates and automatic gas optimization. Batch operations reduce the number of transactions needed, lowering the probability of a single failed transaction causing cascading issues.
What Causes ENS Domain Expiration and Grace Period Errors?
ENS domains are not permanent—they must be renewed periodically. The registration period can be 1 to 100 years, but once expired, three phases occur:
- Grace period (90 days): The domain is still owned but cannot be resolved. You can renew at standard prices.
- Premium period (21 days): The domain enters a Dutch auction, with starting prices that decrease over time based on the original registration fee.
- Public release: Anyone can register the domain at standard rates.
A common error is attempting to resolve a domain during the grace period. The ENS registry will return an empty address because the resolver record is automatically cleared upon expiration. The user sees "address not found" even though they intend to renew. To fix this, simply renew the domain via the ENS Manager—the resolver records are restored from a backup stored in the ENS registry.
Another subtle issue is the "renewal failed" transaction error caused by insufficient allowance for the ERC-20 token used to pay for renewal (if using a token other than ETH). The ENS renewal contract requires the caller to pay in ETH or through the token's approve mechanism. Always verify the token allowance before submitting the renewal transaction.
How to Debug Cross-Chain ENS Resolution Errors
As ENS expands to L2s and sidechains via layer-2 resolution protocols like ENSIP-10, new error classes emerge. Cross-chain errors typically involve:
- Proof verification failure: The off-chain gateway returns a Merkle proof that does not match the on-chain state. This usually occurs because the gateway is out of sync with the L1 contract. Wait a few minutes and retry.
- Gateway timeout: If the gateway does not respond within the RPC timeout, the resolver reverts with a "gateway error." Check that the gateway URL configured in the domain's resolver is correct and reachable. For production applications, use multiple redundant gateways.
- Chain mismatch: Some resolvers are specific to a single chain. Resolving an ENS domain on a chain where the resolver is not deployed yields an empty result. Confirm the resolver contract exists on the chain you are querying.
One effective debugging technique is to enable verbose logging in your dApp or script. Set the ENS_DEBUG environment variable or use an RPC provider that returns detailed error messages, such as Alchemy's eth_call with debug_traceTransaction. This reveals the exact opcode that caused the revert, allowing you to pinpoint whether the failure is in the registry, the resolver, or the gateway.
Best Practices to Prevent ENS Errors
Proactive measures reduce error frequency:
- Set a reminder for renewals — Use calendar alerts at least 30 days before expiration to avoid the grace period.
- Use a multi-signature wallet for domain management to prevent accidental transfers or deletions.
- Document your resolver configuration — Record the resolver address, all records, and any custom gateway URLs in a secure file.
- Test on Sepolia — Before making changes to a production domain, use the ENS testnet (Sepolia) to verify transaction parameters and gas estimates.
- Monitor your domain's on-chain state — Use a service like ens.vision to regularly check resolver status and record integrity.
By understanding the underlying mechanics of ENS—from registry architecture to resolver authorization—you can systematically diagnose and correct errors. The decentralized nature of ENS means that many errors are recoverable without centralized support, provided you follow the correct debugging path. Always verify the chain, the resolver, and the record existence before assuming the domain is permanently broken. With the right approach, even complex cross-chain resolution errors become tractable.