TON Connect not working: 10 errors and fixes

TON Connect was designed to be a “one button and it works” experience, but in practice users keep running into the same dozen problems: the bridge times out, deep-links open the wrong wallet, sessions drop mid-swap, and the picker shows a stranger’s logo instead of the familiar Tonkeeper icon. Most of these are not protocol bugs — they are friction points where three independent components (dApp, bridge, wallet) collide with mobile-OS quirks and stale software versions.

This guide is a handbook: 11 recurring errors, each with a short symptom (what the user sees), a cause (what really happened), and 1–3 fix steps. Useful for both end users and dApp developers — to know when the problem is on your side, when it is in the wallet, and when you need to point the user at their settings.

How TON Connect works: three components that can break

Before diving into errors, fix the mental model. Every TON Connect request flows through three independent entities:

• dApp — the site or mini-app that requests the connection and sends signature requests.
• Bridge — an HTTP relay server that shuttles encrypted messages between dApp and wallet. Tonkeeper defaults to bridge.tonapi.io, MyTonWallet to its own, and there are others. The bridge signs nothing — it is pure transport.
• Wallet — the app that holds the key, shows the request to the user, and signs the transaction.

Each of the three can fail temporarily, misinterpret a request, or carry an outdated protocol version. The errors below sort themselves cleanly across these three.

Error 1: Bridge timeout — the wallet never receives the request

Symptom. You picked Tonkeeper in the dApp picker, a spinner appears, after 60 seconds you get “Bridge timeout” or “Wallet did not respond”.

Cause. The bridge is a separate service and can be down or overloaded. Subtler scenarios: your ISP is blocking the bridge domain, a corporate firewall is killing long-polling connections, or Android’s aggressive background-killer terminated Tonkeeper before the request arrived.

Fix.

1. Close the picker, refresh the dApp, try again — timeouts are often one-off.
2. Open the wallet first, bring it to the foreground, then click Connect in the dApp.
3. If it keeps failing — in Tonkeeper go to Settings → Connected apps → Bridge URL, switch to a backup (for example bridge.tontech.io). MyTonWallet and Tonhub have similar bridge switchers.

Error 2: Deep-link opens the wrong wallet

Symptom. You have Tonkeeper and MyTonWallet both installed, pick Tonkeeper in the picker — MyTonWallet opens instead, showing “Cannot read this connect request”. Or the reverse.

Cause. Both wallets register a handler for the ton:// URL scheme. The OS picks one based on the last install or your saved default. The picker has no way to force a specific app — it hands the deep-link to the OS and hopes for the best.

Fix.

1. On Android: Settings → Apps → Default apps → Opening links → find ton:// and set the wallet you want.
2. iOS has no direct setting — priority goes to the most recently installed app. Reinstall in the order that matches your preference.
3. Workaround: most dApp pickers offer “Connect by QR”. QR connect does not use deep-links — you scan the code from inside the wallet you actually want.

Error 3: Unknown wallet — your wallet is missing from the picker

Symptom. You opened the dApp, hit Connect Wallet, and the picker shows Tonkeeper, MyTonWallet, Tonhub, OKX, and a few others — but not the wallet you actually use.

Cause. The picker hydrates its list from a public wallets-list.json manifest maintained by TON Foundation. Fresh or niche wallets might not be there yet. The same applies to experimental builds and forks.

Fix.

1. Most dApps include an “Other wallet” entry — paste the universal connect URL from your wallet’s TON Connect screen.
2. Use QR. Any wallet that supports TON Connect can scan the picker’s QR, listing or not.
3. Wallet builders — file a PR to ton-blockchain/wallets-list with your app metadata. Once merged, you appear everywhere.

Error 4: Session expired — connect again

Symptom. Yesterday everything worked. Today the same dApp shows a Connect Wallet button as if you had never visited. Inside the wallet, the previous session is gone from Active Sessions.

Cause. The standard allows arbitrary session TTLs, but many dApps default to 30–90 days, and some pick a few hours. After TTL expires the bridge wipes session data and it cannot be revived. Sessions also break when you reinstall the wallet, import the seed on a new device, or clear localStorage in your browser.

Fix.

1. Just reconnect — it is a normal scenario, not a bug.
2. If you reconnect several times a day, check whether your browser wipes cookies on exit (Brave aggressive privacy, Firefox strict mode). dApps store part of the session in localStorage; losing it kills the connection.
3. dApp developers — extend TTL through @tonconnect/sdk configuration so casual users do not get logged out every week.

Error 5: Manifest URL not accessible

Symptom. You opened a mini-app or site, clicked Connect, picked a wallet — but instead of a normal request, the wallet shows “Cannot fetch manifest” or “Invalid manifest”.

Cause. On connect, the wallet downloads the dApp manifest (a JSON with name, icon and permissions) from a URL supplied by the dApp. If that URL is unreachable (CORS-blocked, TLS-invalid, local-dev only, 404), the wallet refuses to proceed.

Fix.

1. As a user — wait 1–2 minutes and retry. CDN hiccups are common.
2. As a developer — confirm that tonconnect-manifest.json is HTTPS-served, replies with Content-Type: application/json, is CORS-friendly, and contains required fields url, name, iconUrl. Use a dev tunnel (Cloudflared, ngrok) when testing from a phone against a local server.

Error 6: Wrong network — connected but the dApp sees zero balance

Symptom. Connection succeeded, your address appears in the dApp, but the balance reads 0 TON or “No assets on this network”. Inside the wallet, you can see your tokens clearly.

Cause. Usually the wallet is in testnet mode while the dApp expects mainnet (or vice versa). TON Connect transmits chain id in the connect response, but Tonkeeper, MyTonWallet and Tonhub each have a separate network switch. A rarer cause: a V5R1 vs W5 wallet contract version where the dApp parses the address format incorrectly.

Fix.

1. Open the wallet, confirm it shows Mainnet at the top.
2. With multi-account wallets, double-check that the active account is the one holding the balance. Tonkeeper shows the connecting account in the connect screen header.
3. Developers — read chain from the TON Connect response and warn the user explicitly when they connect from testnet.

Error 7: Outdated TON Connect SDK — wallet rejects with Unknown method

Symptom. After approving the connect, the wallet returns “Unknown method” or “Method not supported”; the dApp catches an unhandled exception in the SDK.

Cause. TON Connect is a living protocol. New methods get added over time (tonProof, signData, extended sendTransaction options). If the dApp upgrades @tonconnect/sdk but the user’s wallet is months out of date, it does not understand the new call.

Fix.

1. Update the wallet to the latest version (Tonkeeper 4.7+, MyTonWallet 2024+).
2. dApp developers — gate new-method calls behind connector.wallet.device.features and fall back to legacy methods if the feature is absent.

Error 8: Signature went through but the transaction is not on-chain

Symptom. You confirmed in the wallet, saw a success toast, but the explorer has nothing and the dApp keeps showing “Waiting for confirmation”.

Cause. TON Connect returns the signed boc to the dApp, but it is the wallet that actually broadcasts the transaction, not the bridge. If the wallet’s lite-server endpoint is having a bad minute, the transaction can sit in the local outbox or fail to send entirely. Another common cause: the dApp looks for the transaction by the wrong hash — Tonkeeper and MyTonWallet return a boc, not a hash, and the hash has to be computed separately.

Fix.

1. Open the wallet’s Activity view — outgoing transactions show up with real status. Hit refresh if nothing changed.
2. Open Tonviewer or Tonscan, paste your address, look for an outgoing transfer in the last few minutes.
3. dApp developers — do not rely solely on the TON Connect response. Subscribe to your address through TonAPI WebSocket, or poll Toncenter, to confirm on-chain finality.

Error 9: User rejected the request — but the user did nothing of the sort

Symptom. The dApp throws “User rejected the request” (-32000 or a specific TonConnectError code), even though the user never tapped Reject — they just switched apps or did not get around to confirming.

Cause. TON Connect SDK lumps three things into one error: an explicit Reject tap, a 5-minute timeout waiting for signature, and a bridge disconnect mid-request. From the dApp’s perspective they all surface as USER_REJECTED_ERROR, which is misleading.

Fix.

1. End users — reopen the wallet, find the pending request (Tonkeeper exposes it under Requests or in the top bar), confirm it again. If it is gone, click the same button in the dApp and a new one will appear.
2. Developers — distinguish reasons by reading cause and timestamps. A USER_REJECTED_ERROR with no cause is usually a timeout, not a real reject. Show two different messages.

Error 10: Telegram Mini App opens the wallet but returns with an empty session

Symptom. You are inside a Telegram mini-app, tap Connect, Tonkeeper or Wallet opens, you confirm. The mini-app reopens — but the Connect Wallet button is still there as if nothing happened.

Cause. Telegram WebApp reloads the mini-app context entirely when returning from an external app on some Android versions. If the dApp stores TON Connect state only in memory (not localStorage or Telegram CloudStorage), the reload wipes it. Some Telegram builds also fail to restore focus on the right tab and fire the resume event in a minimised state.

Fix.

1. Close and reopen the mini-app — the session inside the wallet is still alive, the dApp will pick it up with a properly written SDK.
2. Mini-app developers — subscribe to tonConnect.onStatusChange and persist wallet.account.address to Telegram CloudStorage or your own backend. On re-entry, restore UI from the saved state without waiting for a fresh connect.

Error 11: Picker opens but Tonkeeper shows a different logo

Symptom. In the picker, the Tonkeeper slot has a different logo or no icon at all. The app name looks slightly off, the connect URL points at a domain you do not recognise.

Cause. Two scenarios. Benign — the dApp loads wallets-list.json from a stale CDN where Tonkeeper still has its previous logo; fixed by updating the SDK. Dangerous — you landed on a phishing clone of the dApp, which served its own wallets list with the same name but a malicious connect URL. Seconds after connecting, you would get a signature request for a draining transaction.

Fix.

1. Do not approve the connect until you verified the dApp URL in the address bar. If the domain is unfamiliar or contains suspicious characters (tonkeeper-app.com instead of tonkeeper.com) — close the tab.
2. If the URL is correct and the logo is still odd, refresh with cache disabled or open the dApp in incognito to rule out stale assets.
3. Keep a cold wallet for funds and a hot wallet for experiments. Never connect the cold one to a dApp you have doubts about. For the full attack taxonomy, see TON Connect phishing and session compromise.

When nothing in the list works

Sometimes the problem does not match any pattern — the wallet hangs on splash, the dApp crashes silently, the picker never opens. Last-resort checklist:

1. Force-quit the wallet and relaunch. Fixes ~30% of stuck-session cases.
2. Clear the dApp cache in your browser for that specific domain. localStorage, cookies, IndexedDB. Reconnect from scratch.
3. Try another wallet on the same dApp. If it works — the first wallet is broken (probably outdated or corrupted state). If not — the dApp is at fault.
4. Try the same wallet on another dApp. If it works — file a support ticket with the original dApp. If not — the wallet is at fault.
5. Check versions. TON Connect 2.0 shipped in 2023, then iterated. Wallets older than mid-2024 risk missing current methods. The same applies to @tonconnect/sdk in dApps.

Wrap-up

Most “TON Connect not working” cases boil down to version mismatch between dApp, SDK and wallet, deep-link handler conflicts, or transient bridge issues. The ten scenarios above cover roughly 90% of tickets that dApp support teams see across the TON ecosystem in 2026.

User discipline: keep the wallet current, never trust the picker without checking the URL, and on weird symptoms check Active Sessions inside the wallet first. Developer discipline: parse SDK errors by type, surface human-readable messages, do not depend on state that can disappear, and log all three component versions on every request.

And remember: TON Connect is transport plus handshake, not magic. When it stays silent, specific pieces failed, and each piece can be checked separately.