Handle Errors
Catch bridge failures, interpret messages, and dispose of signing accounts safely.
This guide describes errors thrown by the bridge, how to catch and branch on messages, and best practices for clearing sensitive material from memory.
Errors from the bridge protocol
Calls to bridge() and quoteBridge() throw when the account is read-only, no provider is configured, the route is invalid, fees exceed bridgeMaxFee, or the destination matches the source chain. The API reference lists representative error.message substrings.
Catch and branch on error messages
You can wrap bridge() in try/catch and inspect error.message for stable substrings:
try {
const result = await bridgeProtocol.bridge({
targetChain: 'arbitrum',
recipient: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
token: '0xdac17f958d2ee523a2206206994597c13d831ec7',
amount: 1000000n
})
console.log('Bridge successful:', result.hash)
} catch (error) {
console.error('Bridge failed:', error.message)
if (error.message.includes('not supported')) {
console.error('Chain or token not supported')
}
if (error.message.includes('Exceeded maximum fee')) {
console.error('Bridge fee above bridgeMaxFee')
}
if (error.message.includes('insufficient funds')) {
console.error('Not enough tokens or gas')
}
if (error.message.includes('must be connected to a provider')) {
console.error('Wallet not connected to blockchain')
}
if (
error.message.includes(
'requires the protocol to be initialized with a non read-only account'
)
) {
console.error('Cannot bridge with read-only account')
}
if (error.message.includes('cannot be equal to the source chain')) {
console.error('Source and destination chain must differ')
}
}Prefer quoteBridge() before bridge() when you want to fail early on fee or route issues without broadcasting.
Best practices
You can clear private key material from memory when a session ends by calling account.dispose() on WalletAccountEvm, or account.dispose() on WalletAccountEvmErc4337:
account.dispose()Call dispose only when you no longer need signing for that account instance. Create a new account object for later sessions.
Combine quoting, fee caps via new Usdt0ProtocolEvm(account, config?), and user-facing validation of targetChain and recipient to reduce avoidable failures.
Next Steps
Review configuration defaults in WDK Bridge USD₮0 EVM Protocol Configuration or return to Get Started for setup.