Skip to main content
You can find some of our troubleshooting guides below when using AppKit. If you encounter another issue, you report us new issue on GitHub. If you have a use case where you need to open AppKit Web SDK inside your mobile app’s in-app browser, you need to handle deep links and Universal Links properly. By default, mobile operating systems restrict how these links work in in-app browsers. To enable wallet connections via deep links, you must explicitly configure your in-app browser to intercept and handle these links. The code examples below show how to properly handle deep links for popular wallet apps like MetaMask and Trust Wallet across different mobile platforms and frameworks.
  • React Native
  • iOS/Swift (WKWebView)
  • iOS/Objective-C (WKWebView)
  • Android/Kotlin (WebViewClient)
  • Android/Java (WebViewClient)
  • Flutter (webview_flutter)
import React from 'react'
import { Linking } from 'react-native'
import { WebView } from 'react-native-webview'

export default function MyWebView() {
  return (
    <WebView
      source={{ uri: 'https://yourdomain.com' }}
      onShouldStartLoadWithRequest={({ url }) => {
        if (url.startsWith('metamask://') || url.startsWith('trust://')) {
          Linking.openURL(url).catch(console.warn)
          return false
        }
        return true
      }}
    />
  )
}

​
Why are the “Connect wallet” and “Network” buttons greyed out?

This can happen if your device is unable to reach the WalletConnect relay service. If you see an error like: 
SocketException: Failed host lookup: 'relay.walletconnect.org' (OS Error: No address associated with hostname, errno = 7)
It usually means your connection is blocked by your VPN or network.

​
Common causes and steps to resolve:

  1. VPN or Firewall settings
    • Some VPNs may block access to the relay service.
    • If you are using a VPN (e.g., Windscribe), try:
      • Switching the VPN protocol to WStunnel.
      • Turning off the Firewall toggle in your VPN settings.
  2. Network restrictions
    • If you’re on a restricted network (e.g., public Wi-Fi, corporate network, or in a restricted country), the relay service may be blocked.
    • Try switching to a different ISP or network.
  3. Connectivity issues
    • Confirm that you can reach relay.walletconnect.org.
    • A 100% packet loss when pinging may indicate the service is blocked on your network.
⌘I