EIP-1193 Error 4902: Unrecognized Chain ID Network Switch Fix
EIP-1193 error 4902 "Unrecognized chain ID" is returned by an EVM web3 wallet when a dApp requests wallet_switchEthereumChain for a target blockchain network that has not yet been added to the user's local wallet configuration. To resolve this error seamlessly, dApp developers must catch error 4902 and automatically execute wallet_addEthereumChain with the chain's verified RPC URL, chain ID, native currency symbols, and block explorer endpoints.
# Root Cause & Technical Architecture
EIP-3326 and EIP-1193 specify that calling `wallet_switchEthereumChain` with a `chainId` not present in the user's local network registry must reject with error code `4902` (Unrecognized Chain). Rather than failing the user experience, standard web3 architecture dictates that dApps implement a fallback catch statement triggering `wallet_addEthereumChain` to prompt the user to register the network.
# 4-Step Actionable Diagnostic Protocol
Step-by-Step ResolutionImplement wallet_addEthereumChain Fallback Pattern
Wrap wallet_switchEthereumChain in a try/catch block. When error code 4902 is caught, invoke wallet_addEthereumChain with full network metadata.
Verify Hexadecimal chainId Formatting
Ensure the chainId parameter is encoded as an unpadded hex string prefixed with 0x (e.g. 0x1 for Ethereum, 0x89 for Polygon, 0xa4b1 for Arbitrum).
Check RPC Endpoint CORS and SSL Compliance
The RPC URL provided in rpcUrls must support HTTPS and allow browser CORS requests; otherwise, the wallet extension will reject network addition.
Manually Add Network via Chainlist.org
If the dApp lacks automatic fallback, users can visit Chainlist.org to add the network and its verified RPC endpoints with one click.
# Diagnostic Verification Code / Command
typescript// Robust Pattern: Switch Chain with Fallback to Add Chain (Error 4902)
async function switchNetwork(provider: any, chainConfig: any) {
try {
await provider.request({
method: 'wallet_switchEthereumChain',
params: [{ chainId: chainConfig.chainIdHex }]
});
} catch (error: any) {
// 4902 indicates chain has not been added to MetaMask yet
if (error.code === 4902 || error?.data?.originalError?.code === 4902) {
await provider.request({
method: 'wallet_addEthereumChain',
params: [chainConfig]
});
} else {
throw error;
}
}
} Launch Derivation Path Inspector
Execute client-side cryptographic simulation and parameter checks safely in your browser via native WebCrypto without sending private keys or mnemonics over the wire.
Read Full Investigation & Recovery Workflow
Explore complete architectural diagrams, edge-case failure trees, and detailed post-mortem analysis in our verified deep guide.
# Related Diagnostic Codes in EVM & JSON-RPC
Related Hex StatusesJSON-RPC Error -32000: Insufficient Funds for Gas * Price + Value
Fix JSON-RPC error -32000 insufficient funds for gas * price + value. Resolve native token balance shortages, fee estimation surges, and gas caps.
JSON-RPC Error -32000: Replacement Transaction Underpriced Fix
Fix JSON-RPC error -32000 replacement transaction underpriced. Apply mandatory 10%+ maxPriorityFeePerGas bump on same nonce to replace stuck mempool txs.
JSON-RPC Error -32000: Nonce Too Low Stale Wallet State Fix
Fix JSON-RPC error -32000 nonce too low. Troubleshoot stale local wallet nonce caches, pending mempool transactions, and reset account state.
# Frequently Asked Questions
FAQ SchemaWhy does MetaMask not have all EVM chains pre-installed?
There are hundreds of EVM chains. MetaMask only includes a few core defaults and relies on EIP-3085 (wallet_addEthereumChain) for user-driven additions.
Is it dangerous to add custom RPC networks?
A malicious RPC provider can display false balances and log IP addresses, but it cannot steal your private keys or sign unauthorized transactions.
How do I convert decimal chain ID to hex for EIP-1193?
Use `0x${chainId.toString(16)}`. For example, Polygon (chainId 137) converts to hex string "0x89".