Ir al contenido principal
↵
Cargando...

User guide: error codes

Below is a non-comprehensive list of errors you may see while using MetaMask. Find the error code you need by scrolling to the relevant section or searching the page. Click any error to expand the troubleshooting steps.

Transaction errors​

Transaction underpriced (ethjs-query while formatting outputs from RPC)

Full error:

Transaction <your transaction # here> failed! Error: [ethjs-query] while formatting outputs from RPC '{"value": {"code":-32000,"message":"transaction underpriced"}}'

This error occurs when the gas price is set too low. It can happen when sending tokens or making a swap via a DEX.

Before submitting a new transaction, check the relevant block explorer (e.g. Etherscan, BscScan, Polygonscan) to make sure you don't have a queue of pending transactions building up.

To fix it, submit a new transaction with higher gas:

  1. Start a new transaction with the same recipient details and token amount, then click Next.
  2. Click the Market icon above the gas details, then click Advanced.
  3. Adjust the following:
    • Gas limit: match or slightly exceed the failed transaction's limit
    • Max priority fee: at least 10% higher (in gwei) than the failed transaction
    • Max fee: at least 30% higher than the failed transaction

If you want to cancel the original pending transaction instead of replacing it, send 0 ETH (or the network's native token) to your own address using the same nonce. See how to speed up or cancel a pending transaction for more detail.

For background on gas, see our gas user guide.

Unable to locate this TxnHash

This error appears when a transaction is stuck locally and has not been submitted to the blockchain.

  1. Open the relevant block explorer for the network you're using — for example, Etherscan for Ethereum or BscScan for BNB Chain. Enter your public wallet address to see all past and pending transactions.
  2. If the transaction appears on the block explorer: wait for it to confirm, or speed it up or cancel it.
  3. If the transaction does not appear on the block explorer: try restarting your browser. If it is still showing as pending in MetaMask after that, you may need to reset your account.
advertencia

Before resetting your account, make sure you have your Secret Recovery Phrase, password, and private keys (for any imported accounts) safely backed up. Resetting clears your local transaction history, but your funds are not lost — all transaction history remains visible on the block explorer.

Smart contract errors​

Exception is thrown in contract code / in contract execution

This error means something went wrong inside the smart contract itself — not in MetaMask. Since this is a problem with the contract's code, it is outside MetaMask's control and we are unable to resolve it directly.

Contact the owners or developers of the contract for assistance. Developers can also post on the MetaMask Community Forums or the Ethereum Stack Exchange to seek help.

Network errors​

Internal JSON-RPC error

If you see "Internal JSON-RPC error" while interacting with a sidechain or custom network:

For more context on custom networks, see our custom networks and sidechains user guide.

No chain ID defined / Missing chain ID / Invalid chain ID

You may see one of the following:

  • Root Error: No chain ID defined
  • Root Error: Missing chain id
  • Root Error: Invalid chain ID

If you manually added the network, go to Settings > Networks and verify the chain ID is correct. You can look up chain IDs on Chainlist or in the network's own documentation.

If you are on Ethereum Mainnet, try toggling to a different network and back again.

Make sure MetaMask is updated to the latest version.

Invalid or missing bridge URL parameter value

Full error: Error: Invalid or missing bridge url parameter value

Reset your account to resolve this error.

advertencia

Before resetting, make sure your Secret Recovery Phrase, password, and private keys (for any imported accounts) are safely saved. After resetting, your transaction history in MetaMask will be cleared, but it remains visible on the relevant block explorer.

Data and type errors​

Cannot read property 'balance' of undefined (and related TypeErrors)

You may see one of the following when opening MetaMask:

  • TypeError: Cannot read property 'balance' of undefined
  • TypeError: Cannot read property 'data' of undefined
  • TypeError: Cannot read property 'selectedMultichainNetworkChainId' of undefined
  • TypeError: Cannot read property 'id' of null
  • TypeError: Cannot read property 'experience' of undefined

Before taking any action, contact MetaMask Support — resetting your account should be avoided where possible and only done if advised.

advertencia

If you do need to reset your account, make sure your Secret Recovery Phrase and the private keys of any imported accounts are securely backed up beforehand. Resetting clears your local transaction history in MetaMask, but your funds are not lost — transaction history is always available on the blockchain.

undefined is not an object / undefined is not a function

You may see one of the following:

  • Root TypeError: undefined is not a function
  • Root TypeError: undefined is not an object

Before taking any action, contact MetaMask Support — resetting your account should be avoided where possible and only done if advised.

advertencia

If you do need to reset your account, make sure your Secret Recovery Phrase and the private keys of any imported accounts are securely backed up beforehand. Resetting clears your local transaction history in MetaMask, but your funds are not lost — transaction history is always available on the blockchain.

number-to-bn while converting number '0xNaN' to BN.js instance

Full error: number-to-bn while converting number '0xNaN' to BN.js instance, error: invalid number value. Value must be an integer, hex string, BN or BigNumber instance. Note, decimals are not supported

This error can appear when performing a transaction. Please contact MetaMask Support — our team will work with you to resolve the issue and help us prevent it from occurring for other users.

Unable to find conversion rate / unable to load balance

This error can occur for one of two reasons:

If the token does not appear in search results after trying the above, you will need to add it as a custom token.

Swap errors​

Error fetching quote / Trade route isn't available

MetaMask Swaps only displays quotes when there is sufficient liquidity on the underlying market — generally, at least a few thousand dollars' worth is needed to keep price impact manageable.

If you see "This trade route isn't available right now", try:

  • Changing the swap amount
  • Switching to a different network
  • Choosing a different token

You can also check CoinGecko, search for the token, and click the Markets tab to see where it can be traded.

EXPIRY PASSED (after a swap)

This error appears on the block explorer when a swap fails because its quote expired. It happens when:

  • You waited too long before confirming the swap in MetaMask, or
  • You submitted the swap at the exact moment the quotes were refreshing.

Simply retry the swap from the beginning.

Account errors​

Invalid password (unlock error)

If you see "Invalid password" when unlocking MetaMask, browser lag may be causing keystrokes to register incorrectly. Try the following before contacting Support:

  1. Type your password slowly, one character at a time, pause for a moment after the last character, then submit.
  2. If that does not work, type your password in a plain text file, copy it, and paste it into the MetaMask password field.
Was this helpful?