troubleshoot-connection

Troubleshoot MetaMask Connect Issues

When to use

Use this skill when:

• A connection attempt hangs, fails, or produces an unexpected error
• React Native apps crash on import or at runtime with missing polyfill errors
• QR codes don't appear or deeplinks don't open MetaMask Mobile
• Solana wallet adapter doesn't detect MetaMask
• Sessions are lost after page reload or disconnect behaves unexpectedly
• You need a systematic checklist to verify a MetaMask Connect integration

Symptom -> Cause -> Fix Reference

---

1. Connection hangs / nothing happens after connect()

Cause A: Extension not detected but preferExtension is true (the default). The SDK falls through to MetaMask Wallet Protocol (MWP) but no QR code is rendered because headless mode is on and there is no display_uri listener.

Fix: Register a display_uri event listener to render the QR code URI before calling connect()

Cause B: A concurrent connect() call is already in progress over MWP.

Fix: Guard against double-clicking. Wrap connect() in a loading-state check and match on the "Existing connection is pending" error message — on MWP this error has no numeric code. (-32002 only appears on the extension transport.)

---

2. User rejected request (code 4001)

Cause: The user clicked "Reject" in MetaMask. This is normal behavior.

Fix: Handle gracefully — show a retry button. Do not treat this as an application error or log it to error-tracking services:

try {
  await client.connect({ chainIds: ['0x1'] });
} catch (err) {
  if (err.code === 4001) {
    // User rejected — show retry UI
    return;
  }
  throw err;
}

---

3. Connection already pending (code -32002)

Cause: A previous connect() call has not yet resolved (the user may still have the MetaMask approval dialog open on mobile).

Fix: Show a message like "Check MetaMask Mobile to approve the connection." Do not call connect() again — the original promise will resolve once the user acts.