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.