Who this is for: Developers and teams building dApps on Tezos using @taquito/beacon-wallet or the Beacon SDK directly. If your project has a “disconnect” or “logout” button, read on.
Over the weekend, changes to the Beacon relay node infrastructure (as part of the ongoing transition toward Octez.Connect and Trilitech Beacon nodes) resulted in a wave of user reports across the ecosystem: wallets failing to connect, pairing requests timing out, and sessions that simply refuse to recover.
We’ve been investigating these reports and working to help affected projects. The underlying causes are varied: some are bugs in the Beacon SDK and Octez.Connect that have only manifested due to this large-scale change of Matrix relay nodes, and others are patterns in dApp code that make the situation worse. We’re continuing to work through these, but there’s one common issue with a straightforward fix that we want to flag immediately.
The problem
Many Tezos dApps use clearActiveAccount() to implement “logout” or “disconnect” functionality. This is incorrect.
clearActiveAccount() only removes the active account reference from localStorage. It does not clear other Beacon session state, including the cached relay node stored under the beacon:matrix-selected-node key. When relay nodes change or go offline, as happened this weekend, end users with stale cached nodes can get stuck in a state where wallet connections silently fail. Without intervention, the only recovery for these users is to manually clear their browser’s localStorage, which is not something most people know how to do.
The correct method for logout is disconnect(), which calls destroy() under the hood and removes all beacon:* keys from localStorage, including the cached relay node and peer data. On next connection, the SDK selects a fresh, reachable node.
What you should do
If your dApp uses @taquito/beacon-wallet, search your codebase for clearActiveAccount. If you’re using it as your logout/disconnect handler, replace it with disconnect():
// Before (incorrect for logout — leaves stale relay node state)
await wallet.client.clearActiveAccount();
// After (correct — clears all Beacon state)
await wallet.disconnect();
Note that after calling disconnect(), the BeaconWallet instance is no longer usable. You’ll need to create a new instance to reconnect:
await wallet.disconnect();
// Reconnect with a fresh instance
const wallet = new BeaconWallet({ name: 'MyDapp' });
await wallet.requestPermissions({ network: { type: NetworkType.MAINNET } });
clearActiveAccount() is still appropriate if you’re implementing account switching within an active session, where you want to preserve the Beacon connection but change which account is active.
For end users currently stuck
If your project’s users are reporting wallet connection failures after this weekend’s changes, the immediate workaround is to have them clear Beacon state from localStorage. Here’s a helpful post from the objkt.com team walking users through the steps.
This is a workaround. Updating your disconnect logic as described above will prevent the problem from recurring, and we’re continuing to investigate other connectivity issues related to the relay node changes.
Context
The execution of the relay node migration and the transition from Beacon SDK to Octez.Connect has surfaced a number of issues that could have been avoided with better coordination and testing across ecosystem teams. We’re working to document these issues and provide clear guidance to minimize disruption.
We’ve updated Taquito’s documentation to explain the difference between these two methods:
- Documentation PR: ecadlabs/taquito#3330
- Test dApp fix: ecadlabs/taquito-test-dapp-vue#143
- Issue: ecadlabs/taquito#3329
If you’re experiencing other wallet connectivity issues unrelated to the clearActiveAccount pattern, please report them on the Taquito GitHub or reach out in the Tezos Discord.
