Error Handling

This guide covers best practices for handling transaction errors, managing fee limits, and cleaning up sensitive data from memory.

Handle Transaction Errors

Wrap transactions in try/catch blocks to handle common failure scenarios such as insufficient balance, invalid addresses, or exceeded fee limits.

Transaction Error Handling

try {
  const result = await account.transfer({
    token: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT mint address
    recipient: '11111111111111111111111111111112',
    amount: 1000000n
  })
  console.log('Transfer submitted:', result.hash)
} catch (error) {
  console.error('Transfer failed:', error.message)
  if (error.message.toLowerCase().includes('insufficient')) {
    console.log('Please add more tokens to your wallet')
  } else if (error.message.toLowerCase().includes('fee')) {
    console.log('The transfer fee exceeds your configured maximum')
  }
}

Handle SOL Transfer Errors

Native SOL transfers can fail for reasons including insufficient balance or invalid recipient addresses.

SOL Transfer Error Handling

async function safeTransfer(account, wallet) {
  try {
    const solBalance = await account.getBalance()
    const transferAmount = 1000000000n // 1 SOL

    if (solBalance < transferAmount) {
      throw new Error('Insufficient SOL balance')
    }

    const quote = await account.quoteSendTransaction({
      to: '11111111111111111111111111111112',
      value: transferAmount
    })
    console.log('Estimated fee:', quote.fee, 'lamports')

    const result = await account.sendTransaction({
      to: '11111111111111111111111111111112',
      value: transferAmount
    })
    console.log('Transaction submitted:', result.hash)

    return result
  } catch (error) {
    if (error.message.includes('Insufficient SOL')) {
      console.error('Please add more SOL to your wallet')
    } else if (error.message.includes('invalid address')) {
      console.error('The recipient address is invalid')
    } else if (error.message.toLowerCase().includes('fee')) {
      console.error('The transaction fee exceeds your configured maximum')
    } else {
      console.error('Transaction failed:', error.message)
    }
    throw error
  } finally {
    account.dispose()
    wallet.dispose()
  }
}

Both transfer and native-send results report submission, not successful execution. Wait for the returned signature with waitForTransaction() and inspect success after the requested commitment before treating the operation as complete.

Handle Prebuilt TransactionMessage Errors

If you pass a prebuilt TransactionMessage, make sure it already has a recent blockhash or durable nonce lifetime, or let WDK inject the latest blockhash for you. If you set feePayer, it must match the wallet address.

Durable nonce flows still need a valid nonce account and signer setup in the message you provide. WDK preserves that lifetime instead of replacing it.

Manage Fee Limits

Set transactionMaxFee when creating the wallet to cap native SOL sendTransaction() and signTransaction() costs. Set transferMaxFee separately for SPL token transfer() costs. Fee caps reject estimates greater than the configured limit, so an estimate equal to the cap is allowed. Retrieve current network rates with getFeeRates() to make informed decisions.

Fee Management

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'lamports')
console.log('Fast fee rate:', feeRates.fast, 'lamports')

const walletWithCaps = new WalletManagerSolana(seedPhrase, {
  provider: 'https://api.mainnet-beta.solana.com',
  transactionMaxFee: 10000000n,
  transferMaxFee: 10000000n
})

Handle Transaction Status Errors

getTransaction() throws ValueError for an invalid base58 signature and NoSuchElementError when a well-formed signature is absent from transaction history. waitForTransaction() treats an unknown signature as transient during propagation and throws TimeoutError if the target is not reached within the configured time.

The Solana implementation does not currently return dropped; a never-landed or evicted signature times out. A confirmed or final receipt can still have success: false, so finality must not be used as an execution-success check.

Dispose of Sensitive Data

Call dispose() on accounts and wallet managers to clear private keys and sensitive data from memory when they are no longer needed.

Memory Cleanup

account.dispose()

wallet.dispose()

Always call dispose() in a finally block or cleanup handler to ensure sensitive data is cleared even if an error occurs.