Troubleshooting

Common Issues

Solutions to common problems you might encounter when building with LaserEyes.

Connection Issues

Wallet Not Detected

The wallet extension is installed but not being detected by LaserEyes.

Solution:

Ensure the wallet extension is properly installed and enabled in your browser. Try refreshing the page or restarting your browser.

// Check if wallet is available
const { isWalletAvailable } = useLaserEyes()

if (!isWalletAvailable) {
  // Show wallet installation prompt
}

Network Mismatch

Wallet is connected to a different network than what's configured in LaserEyes.

Solution:

Ensure your wallet and LaserEyes provider are configured for the same network (mainnet/testnet).

<LaserEyesProvider
  config={{
    network: MAINNET, // or TESTNET
    enforceNetwork: true // Will enforce network matching
  }}
>

Transaction Issues

Transaction Failures

Transactions are failing or getting stuck in a pending state.

Solution:

Check for sufficient balance, proper fee estimation, and network congestion. Use the onError callback to handle failures gracefully.

const { sendBTC } = useLaserEyes()

try {
  await sendBTC({
    address: recipient,
    amount: "1000000", // in sats
    feeRate: "high", // Use higher fee rate during congestion
  })
} catch (error) {
  // Handle error appropriately
  console.error('Transaction failed:', error)
}

Inscription Errors

Issues with inscribing or transferring ordinals and BRC-20 tokens.

Solution:

Verify inscription ownership, check for proper UTXO selection, and ensure sufficient balance for fees.

const { getInscriptions, transferInscription } = useLaserEyes()

// Get all inscriptions first
const inscriptions = await getInscriptions()

// Verify ownership before transfer
const inscription = inscriptions.find(i => i.id === inscriptionId)
if (inscription?.owner !== address) {
  throw new Error('Inscription not owned by connected wallet')
}

State Management

Stale State

Wallet state not updating after transactions or network changes.

Solution:

Use the refresh methods provided by LaserEyes to manually update state when needed.

const { refreshBalance, refreshInscriptions } = useLaserEyes()

// After a transaction completes
await refreshBalance()
await refreshInscriptions()

Permission Issues

Wallet permissions being requested multiple times or unexpectedly.

Solution:

Implement proper permission handling and state persistence using the LaserEyes storage options.

const { requestPermission, hasPermission } = useLaserEyes()

// Check permission before requesting
if (!await hasPermission('sign')) {
  await requestPermission('sign')
}

Performance Issues

Slow Data Loading

Wallet data and inscriptions taking too long to load.

Solution:

Implement proper loading states and consider using the LaserEyes caching system.

const { getInscriptions, getCachedInscriptions } = useLaserEyes()

// Use cached data first
const cached = getCachedInscriptions()
if (cached) {
  // Show cached data immediately
  setInscriptions(cached)
}

// Then fetch fresh data
const fresh = await getInscriptions()
setInscriptions(fresh)

Memory Leaks

Application performance degrading over time due to subscription handling.

Solution:

Properly cleanup subscriptions and event listeners when components unmount.

useEffect(() => {
  const unsubscribe = subscribeToWalletEvents()
  
  // Cleanup on unmount
  return () => {
    unsubscribe()
  }
}, [])

Still Having Issues?

Open an Issue

Report bugs and request features on our GitHub repository

Debugging Guide

Learn advanced debugging techniques for LaserEyes apps

Testing

Best Practices