> For the complete documentation index, see [llms.txt](https://docs.astralbeam.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.astralbeam.io/using-astralbeam/troubleshooting.md).

# 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](https://www.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](/using-astralbeam/connecting-wallets.md))

## 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](https://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

### Mint Reverts with "User error: 60045" (Erc20LockerNotSet)

**Symptoms:**

* Lock confirmed on the EVM chain, relayers reach signature threshold, but the Casper mint keeps failing
* Relayer logs show `Failed to submit mint … User error: 60045`

**Cause:** TokenFactory v7 verifies mints against a per-source-chain `erc20_lockers` mapping. After an in-place contract upgrade, this mapping starts **empty** (it is only seeded on fresh installs), so mints from any unseeded chain revert.

**Solution (operator/admin):** Seed the locker for the source chain, then let the relayers retry:

```bash
bridge-cli admin casper-set-erc20-locker --chain-id <source-chain-id> --address <locker-address>
```

### Unlock Reverts with "User error: 60046" (AttestedAssetMismatch)

**Symptoms:**

* Wrapped burn confirmed on the EVM chain, relayers reach signature threshold, but the Casper `unlock_native` keeps failing
* Relayer logs show `Failed to submit unlock_native … User error: 60046`

**Cause:** The relayers signed an attestation naming a specific CEP-18 asset (`cep18_contract_hash`), but the TokenFactory's live wrapped→native mapping now resolves that wrapped token to a **different** CEP-18 contract. This typically means an admin re-mapped the token (via `casper-update-native-token-mapping`) between the burn being signed and the unlock being submitted. The contract refuses to release an asset the relayers never attested to (attested-asset safety guard).

**Solution (operator/admin):**

1. Verify the current mapping: `bridge-cli casper TokenFactory get_native_token <wrapped-address> <chain-id>`
2. If the re-mapping was intentional and the old attestation is legitimate, restore the original mapping, let the relayers replay the unlock, then re-apply the new mapping.
3. If the mapping was NOT changed by a known admin action, treat this as a security incident — the guard just blocked a mismatched release.

## 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:

   ```bash
   curl "https://api.csprbridge.com/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](https://sepolia.etherscan.io)
   * Base Sepolia: [sepolia.basescan.org](https://sepolia.basescan.org)
   * Casper: [testnet.cspr.live](https://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](https://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](/using-astralbeam/getting-testnet-tokens.md)
* Get more CSPR from the [Casper faucet](https://testnet.cspr.live/tools/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/cspr-bridge/issues](https://github.com/make-software/cspr-bridge/issues)
* **Documentation**: This GitBook site
* **API Status**: Check `/api/v1/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:**

   ```bash
   # Check if your transaction is tracked
   curl "https://api.csprbridge.com/api/v1/transactions?address=YOUR_ADDRESS"
   ```
3. **Verify token addresses:**
   * Are you using official token addresses?
   * Is the token supported on both chains?
4. **Check bridge status:**

   ```bash
   curl "https://api.csprbridge.com/api/v1/health"
   ```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.astralbeam.io/using-astralbeam/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.