Troubleshooting

This guide helps you resolve common issues when using AstralBeam.

Wallet Connection Issues

Casper Wallet Not Detected

Symptoms:

• "Install Casper Wallet" message appears
• Connect button doesn't respond

Solutions:

1. Install Casper Wallet from casperwallet.io
2. Refresh the page after installation
3. Check if the extension is enabled in your browser
4. Try disabling other wallet extensions that might conflict

MetaMask Not Connecting

Symptoms:

• Wallet modal appears but nothing happens
• Connection times out

Solutions:

1. Ensure MetaMask is unlocked
2. Check for pending connection requests in MetaMask
3. Clear MetaMask's connected sites and reconnect
4. Disable other wallet extensions temporarily

Wrong Network in MetaMask

Symptoms:

• "Wrong Network" warning appears
• Transactions fail with network mismatch

Solutions:

1. Click "Switch Network" in the bridge interface
2. Or manually switch in MetaMask:
   • Click network dropdown
   • Select "Sepolia" or "Base Sepolia"
3. If network not listed, add it manually (see Connecting Wallets)

Transaction Issues

Transaction Stuck on "Approval"

Symptoms:

• Progress stuck at approval step
• MetaMask shows no pending transactions

Solutions:

1. Check MetaMask for any pending requests
2. If no request appears, refresh the page and try again
3. Ensure you have enough ETH for gas
4. Try increasing gas price if network is congested

Transaction Stuck on "Lock"

Symptoms:

• Approval completed but lock transaction not appearing
• MetaMask not showing second transaction

Solutions:

1. Wait for approval to fully confirm (1-2 blocks)
2. Check MetaMask for pending lock transaction
3. Ensure sufficient ETH for:
   • Lock transaction gas
   • Bridge fee (0.0001 ETH)
4. Refresh page and check Transactions page for status

Long Finality Wait (EVM → Casper)

Symptoms:

• Progress stuck at "Waiting for Finality"
• Timer shows many minutes remaining

This is normal behavior:

• Ethereum requires ~64 blocks (~13 minutes) for finality
• This protects against chain reorganizations
• Your transaction is safe - you can close the page

If waiting longer than 20 minutes:

1. Check the source transaction on Etherscan
2. Verify it has sufficient confirmations
3. Check the Transactions page for any errors

Attestation Taking Too Long

Symptoms:

• Stuck on "Relayer Attestation" for >5 minutes
• Progress not advancing

Possible causes:

1. High transaction volume: Relayers processing many requests
2. Network issues: Relayer P2P connectivity problems
3. Insufficient relayers: Less than M relayers online

Solutions:

1. Wait - attestations typically complete within 1-5 minutes
2. Check the Transactions page for detailed status
3. If >15 minutes, contact support with your transaction hash

Tokens Not Appearing After Bridge

Symptoms:

• Bridge shows "Completed" but no tokens in wallet
• Balance unchanged

Solutions:

For EVM tokens:

1. Ensure you're on the correct network (Sepolia/Base)
2. Add token manually to MetaMask using contract address
3. Check Etherscan for your address to verify receipt
4. Wait a few minutes for wallet to sync

For Casper tokens:

1. Check testnet.cspr.live for your account
2. Look under "Tokens" tab for CEP-18 tokens
3. Casper Wallet may need refresh to show new tokens

Balance and Amount Issues

"Insufficient Balance" Error

Causes:

1. Not enough tokens to bridge
2. Not enough native tokens for gas (ETH/CSPR)
3. Trying to bridge more than available

Solutions:

1. Check your token balance matches the amount
2. Keep ETH reserved for gas fees (~0.01 ETH)
3. Keep CSPR reserved for Casper gas (~5 CSPR)

"Insufficient Chain Liquidity" Error

Cause: More tokens being unlocked than are locked on the destination chain.

Solutions:

1. Try a smaller amount
2. Check current liquidity via API:

   curl "https://api.testnet.astralbeam.io/api/v1/tokens"
   

3. Wait for more tokens to be bridged to that chain

Amount Shows "0" After Entering Value

Causes:

1. Token not selected
2. Invalid amount format
3. Amount exceeds balance

Solutions:

1. Select a token first
2. Use numbers only (no commas or letters)
3. Use "Max" button to set maximum available

Network and Connectivity

"Failed to Fetch" Errors

Causes:

1. Internet connectivity issues
2. Bridge API temporarily unavailable
3. Browser blocking requests

Solutions:

1. Check your internet connection
2. Try refreshing the page
3. Clear browser cache
4. Try a different browser
5. Disable VPN if using one

RPC Errors

Symptoms:

• "RPC Error" messages
• Transactions not submitting

Solutions:

1. Switch to a different RPC endpoint in MetaMask
2. For Sepolia, try:
   • https://rpc.sepolia.org
   • https://ethereum-sepolia-rpc.publicnode.com
3. For Casper, the bridge uses its own RPC - no action needed

Transaction Not Found on Explorer

Possible causes:

1. Transaction not yet submitted
2. Transaction failed before submission
3. Looking on wrong network/explorer

Solutions:

1. Check the Transactions page for status
2. Verify you're on the correct explorer:
   • Sepolia: sepolia.etherscan.io
   • Base Sepolia: sepolia.basescan.org
   • Casper: testnet.cspr.live
3. Wait a few minutes for indexing

Casper-Specific Issues

Deploy Failed on Casper

Symptoms:

• Burn transaction shows "Failed" on CSPR.live
• Error in Casper Wallet

Common causes:

1. Insufficient CSPR for gas (~2.5 CSPR needed)
2. Contract execution error
3. Invalid parameters

Solutions:

1. Ensure you have at least 5 CSPR for gas
2. Check the deploy error on CSPR.live
3. Try again with a smaller amount

CEP-18 Token Not Visible

Solutions:

1. Go to testnet.cspr.live
2. Search for your account hash
3. Click "Tokens" tab
4. Your CEP-18 tokens should appear there
5. Casper Wallet auto-detects tokens with balance

Casper Wallet Shows Wrong Balance

Solutions:

1. Refresh Casper Wallet
2. Disconnect and reconnect to the bridge
3. Check actual balance on CSPR.live
4. Clear Casper Wallet cache if available

Common Error Messages

"User rejected the request"

Meaning: You cancelled the transaction in your wallet.

Solution: Try again and approve when wallet prompts.

"Insufficient funds for gas"

Meaning: Not enough native tokens for transaction fees.

Solutions:

• Get more ETH from a Sepolia faucet
• Get more CSPR from the Casper faucet

"Execution reverted"

Meaning: Smart contract rejected the transaction.

Common causes:

1. Token not approved for spending
2. Amount exceeds allowance
3. Contract paused

Solutions:

1. Check approval amount matches or exceeds bridge amount
2. Try the transaction again (approval may have failed)
3. Check if bridge is under maintenance

"Nonce too low"

Meaning: MetaMask has a pending transaction or incorrect nonce.

Solutions:

1. Wait for pending transactions to complete
2. Reset MetaMask account:
   • Settings → Advanced → Reset Account
   • This clears transaction history (not funds)

"Transaction underpriced"

Meaning: Gas price too low for current network conditions.

Solutions:

1. Increase gas price in MetaMask
2. Wait for network congestion to decrease
3. Enable "Aggressive" gas estimation in MetaMask

Getting Help

Information to Provide

When seeking help, include:

1. Transaction details:

   • Source chain and address
   • Destination chain and address
   • Token and amount
   • Transaction hash (if available)

2. Error information:

   • Exact error message
   • Screenshot of the error
   • Step where error occurred

3. Environment:

   • Browser and version
   • Wallet extension and version
   • Operating system

Support Channels

• GitHub Issues: github.com/make-software/astralbeam-core/issues
• Documentation: This GitBook site
• API Status: Check /api/v1/stats/health endpoint

Self-Service Checks

Before contacting support:

1. Check transaction on explorers:

   • Did the source transaction confirm?
   • Is the destination transaction pending?

2. Check the API:

   # Check if your transaction is tracked
   curl "https://api.testnet.astralbeam.io/api/v1/transactions/address/YOUR_ACCOUNT_HASH_OR_EVM_ADDRESS"
   

3. Verify token addresses:

   • Are you using official token addresses?
   • Is the token supported on both chains?

4. Check bridge status:

   curl "https://api.testnet.astralbeam.io/api/v1/stats/health"