Troubleshooting Guide

Common issues and their solutions for MCP Wallet.

Installation Issues

Build Errors on macOS

Problem: Build fails with "Command not found" or dependency errors

Solutions:

1. Install Xcode Command Line Tools

   xcode-select --install

2. Update Homebrew and Node

   brew update
   brew upgrade node

3. Clear cache and reinstall

   rm -rf node_modules
   rm -rf src-tauri/target
   npm install

Build Errors on Windows

Problem: Build fails with "MSVC not found" or similar errors

Solutions:

1. Install Visual C++ Build Tools

   • Download from Microsoft
   • Install "Desktop development with C++"

2. Install WebView2

   • Download from Microsoft

3. Restart computer after installation

Rust Installation Issues

Problem: rustc: command not found

Solutions:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Verify installation
rustc --version
cargo --version

Wallet Issues

Can't Unlock Wallet

Problem: "Incorrect password" or wallet won't unlock

Solutions:

1. Check password carefully

   • Passwords are case-sensitive
   • Check Caps Lock is off
   • Try typing in notepad first to verify

2. Database corruption

   # Backup first!
   # macOS
   cp ~/Library/Application\ Support/com.mcp-wallet.app/wallet.db ~/wallet-backup.db
   
   # Then try deleting and re-importing with seed phrase

3. Recover with seed phrase

   • Delete the app data
   • Restart MCP Wallet
   • Choose "Import Wallet"
   • Enter your 12-word seed phrase

Backup First

Always backup your seed phrase before deleting wallet data!

Seed Phrase Invalid

Problem: "Invalid seed phrase" when importing

Solutions:

1. Check word spelling

   • All words must be from BIP39 word list
   • No extra spaces
   • Correct order

2. Check word count

   • Must be exactly 12 words
   • No extra or missing words

3. Try different word variations

   • Some words have similar spellings
   • Check against BIP39 word list

Balance Shows Zero

Problem: Imported wallet but balance is zero

Solutions:

1. Check correct network

   • Go to Settings → Network
   • Verify you're on the same network where you have funds
   • BSC Mainnet vs Testnet

2. Wait for sync

   • Sometimes takes a few seconds to load balance
   • Click refresh button

3. Check block explorer

   • Copy your address
   • Check on BSCScan
   • Verify funds are actually there

OAuth & AI Integration

Authorization Dialog Not Appearing

Problem: Clicked "Auth" but no dialog shows in MCP Wallet

Solutions:

1. Check wallet is unlocked

   • MCP Wallet must be running and unlocked
   • Unlock screen should not be showing

2. Check API enabled

   • Go to Settings → Accounts
   • Find your account
   • Ensure "Enable API" is ON

3. Check MCP Server running

   • Go to Settings → MCP Server
   • Status should show "Running"
   • If not, click "Start Server"

4. Restart MCP Wallet

   • Close completely
   • Reopen and unlock
   • Try authorization again

HTTP 500 Error in Claude Code

Problem: Claude Code shows "HTTP 500: Internal Server Error"

Solutions:

1. Update MCP Wallet

   • Make sure you have the latest version
   • OAuth server was fixed in recent updates

2. Check MCP Server logs

   • Go to Settings → Logs
   • Look for error messages
   • Share logs when reporting issues

3. Restart services

   # Close MCP Wallet completely
   # Restart Claude Code
   # Reopen MCP Wallet and unlock
   # Try again

4. Verify OAuth server

   • Server should be: https://mcp-wallet-oauth.dev-taoist.workers.dev
   • Check it's accessible: try visiting in browser

401 Unauthorized Error

Problem: "401 Unauthorized" or "Invalid token"

Solutions:

1. Re-authorize

   • Run /mcp command in Claude Code again
   • Complete authorization flow
   • Tokens may have expired

2. Check token expiry

   • Access tokens expire after 1 hour
   • Refresh tokens expire after 30 days
   • Need to re-auth if expired

3. Clear Claude Code cache

   # macOS/Linux
   rm -rf ~/.claude/mcp-cache/
   
   # Windows
   del /s /q %APPDATA%\.claude\mcp-cache\

"Connection Refused" Error

Problem: Can't connect to localhost:8580

Solutions:

1. Check MCP Server port

   • Default is 8580
   • Go to Settings → MCP Server
   • Verify port number

2. Check firewall

   • Allow MCP Wallet through firewall
   • Allow localhost connections

3. Check port not in use

   # macOS/Linux
   lsof -i :8580
   
   # Windows
   netstat -ano | findstr :8580

4. Try different port

   • Go to Settings → MCP Server
   • Change to 8581 or 8582
   • Update Claude Code config

Transaction Issues

Transaction Rejected

Problem: Transaction rejected with error

Solutions:

1. Check balance

   • Need enough tokens + gas fees
   • For BNB transfer: need extra BNB for gas
   • For USDT transfer: need BNB for gas

2. Check network

   • Verify correct network selected
   • Testnet vs Mainnet
   • Recipient address on same network

3. Check API access (for AI transactions)

   • API enabled in Settings → Accounts
   • OAuth token still valid

Insufficient Funds Error

Problem: "Insufficient funds for gas"

Solutions:

1. Get more BNB

   • Need BNB to pay gas fees
   • Even for USDT transfers
   • Typical gas fee: ~0.0005 BNB

2. Check total cost

   Total needed = Amount + Gas Fee
   Example: Send 10 USDT
   - USDT: 10
   - Gas (in BNB): ~0.0005
   - Need: 10 USDT + 0.0005 BNB

Transaction Stuck/Pending

Problem: Transaction shows "pending" for long time

Solutions:

1. Wait - Network may be congested

   • Normal: 5-30 seconds
   • Congested: 1-5 minutes
   • If >10 minutes, investigate

2. Check block explorer

   • Copy transaction hash
   • Check on BSCScan
   • See actual status

3. Check wallet balance

   • Transaction may have failed due to insufficient gas
   • Check if balance changed

Wrong Network Error

Problem: "Wrong network" or transaction failed

Solutions:

1. Verify network

   • Settings → Network
   • Check matches intended network
   • Testnet (97) vs Mainnet (56)

2. Switch network

   • Change in Settings
   • Restart if needed

3. Verify recipient address

   • Make sure address is valid for network
   • Don't send Ethereum addresses BSC tokens

Performance Issues

App Slow to Start

Solutions:

1. Clear cache

   # macOS
   rm -rf ~/Library/Caches/com.mcp-wallet.app/
   
   # Windows
   del /s /q %APPDATA%\com.mcp-wallet.app\Cache\

2. Check database size

   • Large transaction history may slow things
   • Consider archiving old data

3. Restart app

   • Complete close (not just minimize)
   • Reopen

High Memory Usage

Solutions:

1. Restart app
2. Close unused tabs/windows
3. Update to latest version

Error Messages

"Database locked"

Solutions:

1. Close other instances

   • Only run one instance of MCP Wallet
   • Check Task Manager (Windows) or Activity Monitor (macOS)

2. Delete lock file

   # Find and delete .lock files in app data directory
   # macOS
   find ~/Library/Application\ Support/com.mcp-wallet.app/ -name "*.lock" -delete

"Failed to fetch"

Solutions:

1. Check internet connection
2. Check RPC endpoint
   • Settings → Network → Advanced
   • Try different RPC endpoint
3. Firewall blocking
   • Allow MCP Wallet through firewall

"Nonce too low"

Solutions:

1. Wait for previous transaction

   • Previous transaction still pending
   • Wait for confirmation

2. Restart app

   • Refreshes nonce tracking

Logging & Debugging

Enable Debug Logs

1. Go to Settings → Advanced
2. Enable "Debug Logging"
3. Logs saved to:
   • macOS: ~/Library/Logs/mcp-wallet/
   • Windows: %APPDATA%\mcp-wallet\logs\
   • Linux: ~/.local/share/mcp-wallet/logs/

View Logs

# macOS/Linux
tail -f ~/Library/Logs/mcp-wallet/app.log

# Windows
type %APPDATA%\mcp-wallet\logs\app.log

Report Issue with Logs

When reporting issues:

1. Enable debug logging
2. Reproduce the issue
3. Export logs
   • Settings → Logs → Export
4. Create GitHub issue
   • Include log file
   • Describe steps to reproduce
   • Include screenshots

Recovery Scenarios

Lost Password

1. You have seed phrase: ✅ Can recover

   • Delete wallet data
   • Import with seed phrase
   • Set new password

2. No seed phrase: ❌ Cannot recover

   • Funds are permanently inaccessible
   • This is why seed phrase backup is critical

Lost Seed Phrase

1. Wallet still unlocked: ✅ Can view seed

   • Settings → Security → Show Seed Phrase
   • Enter password
   • Write down seed phrase NOW

2. Wallet locked + no seed: ❌ Cannot recover

   • If you forget password and lost seed phrase
   • Funds are permanently inaccessible

Corrupted Database

1. Have seed phrase: ✅ Can recover

   • Delete database
   • Re-import wallet
   • Transaction history lost, but funds safe

2. No seed phrase: Try recovery

   # Backup corrupted DB first
   cp wallet.db wallet.db.backup
   
   # Try SQLite recovery
   sqlite3 wallet.db ".recover" | sqlite3 wallet-recovered.db

Still Need Help?

If you couldn't find a solution:

1. Check FAQ - /guide/faq
2. Telegram - Community discussion and support
3. GitHub Issues - Report a bug

When asking for help, include:

• Operating system and version
• MCP Wallet version
• Steps to reproduce
• Error messages
• Screenshots (remove sensitive info!)
• Logs (if applicable)

Never Share

Never share:

• Seed phrase
• Private keys
• Password
• Full wallet address (in public forums)