Troubleshooting

Diagnostic Checklist

When something isn't working, check these in order:

1. Is registerWidgetElement() called? Required before using HTML tags. Not needed for the imperative API.
2. Is the container in the DOM? The imperative API throws TF5001 if the CSS selector doesn't match.
3. Is the API reachable? Test with: curl <your-api-endpoint>/v1/chains
4. Is a wallet adapter provided? Without one, "Connect Wallet" only fires the onConnectWallet callback.
5. Is the correct chain connected? Some routes require the wallet to be on a specific chain.
6. Are there console errors? Check the browser DevTools console for [TokenFlight] warnings.

Console Warnings

Warning	Meaning	Fix
No wallet adapter configured	No adapter — wallet features limited	Provide walletAdapter or handle onConnectWallet
Wallet not connected	Wallet action attempted without connection	Connect the wallet first
API request failed	Network request failed	Check API reachability and network

Common Issues

Widget renders but is completely empty

• CSP violation: If your page has a strict Content Security Policy, inline styles may be blocked. Use the csp-nonce attribute. See CSP Guide.
• Shadow DOM not supported: Very old browsers may not support Shadow DOM v1. See Browser Compatibility.

Widget shows but no tokens appear

• The API needs to respond with token data. Check network requests in DevTools for failed /v1/tokens or /v1/chains calls.
• If using supportedChainIds on the wallet adapter, ensure the listed chains are supported by the API.

Quotes never load

• Check the network tab for POST /v1/quotes requests.
• A 15-second timeout applies. Slow networks may trigger TF3002.
• Verify the token pair is valid — not all combinations have routes.

Wallet connection fails

• No window.ethereum: The ethers adapter requires an injected provider. If using a mobile browser without a wallet extension, consider AppKit with WalletConnect.
• Wrong chain: Some adapters auto-switch chains. If switching fails, TF2003 is emitted.

Transaction signed but order stuck

• Cross-chain orders can take 10+ minutes depending on the bridge and chains involved.
• Check the source chain transaction on a block explorer using the txHash.
• Query GET /v1/orders/:address from your backend for the latest status.

Wallet shows zero balance on a supported chain

The widget queries token balances only for chains listed in supportedChainIds. When using wallet adapters like AppKitWalletAdapter or WagmiWalletAdapter, this list is automatically derived from your wallet library's configured networks.

If a chain is supported by the API but missing from your wallet config, the widget won't query balances for it.

Fix: Add the missing chain to your wallet library configuration:

// AppKit example — add Unichain (chainId 130)

const unichain = defineChain({
  id: 130,
  name: 'Unichain',
  nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
  rpcUrls: { default: { http: ['https://mainnet.unichain.org'] } },
  blockExplorers: { default: { name: 'Uniscan', url: 'https://uniscan.xyz' } },
})

createAppKit({
  networks: [mainnet, arbitrum, base, polygon, unichain],
  // ...
})

Or override supportedChainIds explicitly on the adapter:

const adapter = new AppKitWalletAdapter(appkit, {
  supportedChainIds: [1, 42161, 8453, 137, 10, 130],
})

Network Debugging

The widget only makes HTTP requests to:

1. API endpoint — the configured apiEndpoint for quotes, builds, submissions, and order tracking.
2. Chain icons — <apiEndpoint>/v1/chain/{chainId}/icon for chain logo images.
3. Token icons — URLs from the logoURI field in token metadata (various CDNs).

No other domains are contacted. No analytics, no tracking, no third-party scripts.

Distinguishing Error Sources

Symptom	Likely Source	How to Verify
Widget won't render	SDK integration issue	Check console for TF5001/TF5002 errors
"Connect Wallet" does nothing	Missing adapter or callback	Check if onConnectWallet is configured
Wallet popup appears then fails	Wallet issue (wrong chain, insufficient gas)	Check wallet error message
Quote loads but swap fails	API or route issue	Check POST /v1/quotes response in Network tab
Tx signed but nothing happens	Network/bridge delay	Check txHash on block explorer

Getting Help

If you can't resolve an issue:

1. Check the FAQ for common questions
2. Contact support with:
   • Browser and version
   • SDK version (@tokenflight/swap version from package.json)
   • Adapter being used
   • Console errors (screenshots help)
   • Network request/response for failed API calls