Troubleshooting

​

Before you troubleshoot

• Use a supported Node.js version. The documentation examples and repository use Node.js 22.
• Confirm the package version in your project matches the version documented in package.json.
• Use Sepolia or another supported testnet while developing.
• Keep API keys and wallet private keys in server-side environment variables.
• Confirm the parent ENS name is configured for the operation you are attempting.

​

Authentication errors

​

401 or 403 from the Offchain API

1. Generate or copy the key in the Namespace App.
2. Confirm your server loaded NAMESPACE_API_KEY.
3. Use an address-based key as defaultApiKey, or map a domain-based key to the exact parent name.
4. Do not expose the key in browser code or commit it to source control.

import { createOffchainClient } from '@thenamespace/offchain-manager';

const apiKey = process.env.NAMESPACE_API_KEY;
if (!apiKey) throw new Error('Missing NAMESPACE_API_KEY');

const client = createOffchainClient({
  mode: 'sepolia',
  defaultApiKey: apiKey,
});

​

Subname creation errors

​

The subname already exists

const { isAvailable } = await client.isSubnameAvailable(
  'alice.example.eth',
);

if (!isAvailable) {
  throw new Error('alice.example.eth is already registered');
}

​

Records fail validation

• Use a complete, valid address for the selected ChainName.
• Use the label only in label; do not pass the full subname.
• Pass the parent separately in parentName.
• Follow ENSIP-15 normalization rules for labels.

​

Minting errors

​

canMint is false

const details = await mintClient.getMintDetails({
  parentName: 'example.eth',
  label: 'alice',
  minterAddress: account.address,
});

if (!details.canMint) {
  throw new Error(details.validationErrors.join(', '));
}

​

The transaction simulation fails

• The wallet client and public client use the same chain.
• The parent name is activated and listed for that chain.
• The wallet has enough native currency for the mint price and gas.
• You pass the value returned by getMintTransactionParameters unchanged.
• You generated the transaction parameters immediately before simulation so price and signature data are current.

​

Resolution errors

​

An offchain subname does not resolve

1. Confirm the subname exists in the Namespace App.
2. Confirm the parent name uses the Namespace Hybrid resolver.
3. Check that the consuming wallet or app supports CCIP Read.
4. Test the name through Resolvio to separate resolver issues from client integration issues.

​

An address or text record is missing

​

Network and RPC errors

• Confirm the RPC endpoint supports the chain used by the wallet and public clients.
• Check the provider dashboard for rate limiting or an invalid token.
• Avoid mixing mainnet parent names with testnet configuration.
• Retry transient 429 and 5xx errors with bounded exponential backoff.

​

Get more help