Troubleshooting

Common issues and solutions for wallet connections, transactions, and gas estimation.

Wallet Connection Issues

❌ "Kukai-Embed Already Present" Error

This error occurs when Kukai is initialized multiple times.

Solution: This has been fixed in the latest version. The wallet store now prevents duplicate initialization. If you still see this error, ensure you're using the latest code and only one WalletProvider in your app.

❌ Wallet Not Connecting

Wallet connection button doesn't respond or fails silently.

Debug Steps

// 1. Check if wallets are initialized
const { isInitialized } = useTezos();
console.log('Wallets initialized:', isInitialized);

// 2. Check for errors in browser console
// Look for wallet-related errors during connection

// 3. Verify wallet extension is installed
// Temple Wallet: chrome-extension://ookjlbkiijinhpmnjffcofjonbfbgaoc
// Check in browser extensions page

// 4. Check network permissions
// Some wallets require specific network permissions

❌ State Not Restoring on Refresh

Wallet connection is lost when page refreshes.

Check Setup

// Verify WalletProvider is wrapping your app
// app/layout.tsx should have:

<WalletProvider>
  <div className="app">
    {children}
  </div>
</WalletProvider>

// Check browser storage for wallet data:
// 1. Open DevTools → Application → Local Storage
// 2. Look for keys starting with "beacon:" or "kukai:"
// 3. If missing, wallet didn't save connection properly

Transaction Problems

❌ "Counter in the Future" Error

Transaction fails with counter mismatch error.

Cause: This happens when multiple transactions are sent too quickly or when there's a counter synchronization issue.

Solution: The new transaction system includes automatic gas estimation with retry logic that handles this. Wait for transactions to complete before sending new ones.

❌ Gas Estimation Fails

Transaction gas estimation keeps failing or timing out.

Gas Estimation Debug

// The new system has built-in retry logic:

async function debugGasEstimation() {
  const { Tezos } = useTezos();
  
  try {
    // Manual estimation test
    const estimate = await Tezos.estimate.transfer({
      to: 'tz1...',
      amount: 1 // 1 XTZ
    });
    
    console.log('Gas estimation successful:', {
      gasLimit: estimate.gasLimit,
      fee: estimate.suggestedFeeMutez,
      storage: estimate.storageLimit
    });
    
  } catch (error) {
    console.error('Gas estimation failed:', error);
    // Check: 
    // - Is wallet connected?
    // - Is recipient address valid?
    // - Does account have sufficient balance?
    // - Is network connection stable?
  }
}

❌ Insufficient Balance for Fees

Transaction fails because account doesn't have enough XTZ for fees.

Solution: Always reserve some XTZ for transaction fees. The transaction form automatically accounts for this by reserving ~0.01 XTZ for fees when calculating maximum sendable amount.

Network & RPC Issues

❌ RPC Connection Timeouts

Operations timeout or fail to connect to Tezos network.

Check RPC Status

// Test RPC connectivity
const { Tezos } = useTezos();

async function testRPC() {
  try {
    // Test basic connectivity
    const head = await Tezos.rpc.getBlockHeader();
    console.log('RPC connected, current block:', head.level);
    
    // Test if wallet is properly set
    const walletPKH = await Tezos.wallet.pkh();
    console.log('Wallet address:', walletPKH);
    
  } catch (error) {
    console.error('RPC test failed:', error);
    // Try different RPC endpoint or check network
  }
}

// Current RPC endpoints:
// Mainnet: https://rpc.tzkt.io/mainnet  
// Ghostnet: https://rpc.tzkt.io/ghostnet

❌ Wrong Network Configuration

App connects to wrong network or wallet shows different network.

Check: Verify your .env.local file has the correct NEXT_PUBLIC_NETWORK setting.
Ghostnet: NEXT_PUBLIC_NETWORK=ghostnet
Mainnet: NEXT_PUBLIC_NETWORK=mainnet

Development Issues

❌ TypeScript Errors

Type errors related to wallet objects or Tezos operations.

Common Type Fixes

// Use proper null checks
const { address, Tezos } = useTezos();

// ❌ Don't do this:
// const balance = await Tezos.tz.getBalance(address);

// ✅ Do this:
if (address) {
  const balance = await Tezos.tz.getBalance(address);
}

// ❌ Don't do this:
// wallet.methodsObject.transfer(...)

// ✅ Do this:
const contract = await Tezos.wallet.at(contractAddress);
await contract.methodsObject.transfer(...).send();

❌ Hot Reload Issues

Wallet state gets corrupted during development hot reloads.

Solution: This is normal during development. Simply refresh the page (Cmd+R / Ctrl+R) to reset wallet state. In production builds, this won't be an issue.

Debug Tools & Commands

Useful debugging commands and tools for diagnosing wallet issues.

Debug Console Commands

// In browser console:

// Check wallet store state
const store = window.__zustand_stores__?.wallet;
console.log('Wallet store:', store);

// Check local storage for wallet data
Object.keys(localStorage).filter(key => 
  key.includes('beacon') || key.includes('kukai')
);

// Test wallet connection manually
const walletStore = /* get from useTezos hook */;
await walletStore.connectWallet();

// Clear all wallet data (reset)
localStorage.clear();
location.reload();

// Check current network
console.log('Network:', process.env.NEXT_PUBLIC_NETWORK);

Browser Extensions

Temple Wallet	Manages Tezos accounts and signs transactions
React DevTools	Inspect React component state and props
Redux DevTools	Works with Zustand stores for state debugging

Getting Help

📖 Documentation

Check other documentation sections for detailed guides

Wallet Integration Guide →Code Examples →Configuration Guide →

🛠️ External Resources

Community resources and official documentation

Taquito Documentation ↗Beacon SDK Docs ↗Kukai Documentation ↗

Tezos Wallet Boilerplate Docs