Troubleshooting

Troubleshooting Guide

🔍 Quick Diagnosis

Health Check Command

Always start troubleshooting with the health check:

sam health

This command provides:

  • ✅ Configuration validation
  • ✅ API connectivity testing
  • ✅ Database integrity checks
  • ✅ Wallet status verification
  • ✅ Tool availability confirmation

Setup Validation

sam setup

Validates:

  • OpenAI API key configuration
  • Fernet encryption key presence
  • Solana RPC connectivity
  • Database accessibility

🚨 Common Issues & Solutions

Configuration Issues

"OPENAI_API_KEY is required"

Solutions:

# Option 1: Run setup wizard
sam onboard

# Option 2: Manual configuration
echo "OPENAI_API_KEY=sk-your-key-here" >> .env
source .env

# Option 3: Environment variable
export OPENAI_API_KEY="sk-your-key-here"

Verification:

sam setup  # Should show API key as valid

"SAM_FERNET_KEY is required"

Solutions:

# Generate new encryption key
sam key generate

# Or manually add to .env
echo "SAM_FERNET_KEY=your-generated-key" >> .env

System Keyring Not Available

Solutions:

# Install keyring dependencies
pip install keyring keyrings.alt  # Linux
# or
pip install keyring               # macOS/Windows

# Or use environment variable fallback
sam key import  # Will use legacy method

Wallet & Key Issues

Private Key Import Fails

Symptoms:

  • "Failed to store private key securely"
  • "Invalid private key format"

Solutions:

# Verify private key format (should be base58)
# Solana private keys are 64-character base58 strings

# Check keyring availability
sam key import  # Will show detailed error

# Use legacy method if keyring fails
# Follow prompts to use environment variable method

Wallet Address Mismatch

Symptoms:

  • Transactions fail with "invalid address"
  • Balance shows for wrong wallet

Solutions:

# Verify wallet address
sam  # Start interactive mode
/wallet  # Shows current wallet address

# Re-import private key
sam key import

# Check configuration
sam setup

API Connectivity Issues

OpenAI API Authentication Failed

Symptoms:

  • "Authentication failed"
  • "Invalid API key"

Solutions:

# Verify API key
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
     https://api.openai.com/v1/models

# Check API key format (should start with 'sk-')
echo $OPENAI_API_KEY | head -c 10  # Should show 'sk-'

# Verify API credits
# Visit https://platform.openai.com/api-keys

Solana RPC Connection Failed

Symptoms:

  • "RPC connection timeout"
  • "Failed to connect to Solana RPC"

Solutions:

# Test RPC endpoint
curl -X POST -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"getVersion"}' \
     $SAM_SOLANA_RPC_URL

# Try different RPC endpoints
export SAM_SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"

# Check network connectivity
ping api.mainnet-beta.solana.com

Brave Search API Issues

Symptoms:

  • Web search tools fail
  • "Brave API key invalid"

Solutions:

# Verify API key
export BRAVE_API_KEY="your-brave-api-key"

# Test API connectivity
curl "https://api.search.brave.com/res/v1/web/search?q=test&key=$BRAVE_API_KEY"

Transaction Issues

Transaction Expired (Stale Blockhash)

Symptoms:

  • "Transaction expired"
  • "Blockhash not found"

Solutions:

# Transactions are time-sensitive, retry immediately
# This is normal for high network congestion

# Use faster RPC endpoint
export SAM_SOLANA_RPC_URL="https://fast-rpc-endpoint.com"

# Reduce slippage for faster execution
export DEFAULT_SLIPPAGE=1

Insufficient Funds

Symptoms:

  • "Insufficient SOL balance"
  • Transaction simulation fails

Solutions:

# Check balance
sam
"check my balance"

# Verify wallet has enough SOL for transaction + fees
# Minimum 0.000005 SOL for transaction fees

# Add funds to wallet
# Transfer SOL from exchange or another wallet

Slippage Too High/Low

Symptoms:

  • "Slippage tolerance exceeded"
  • Failed swaps on volatile tokens

Solutions:

# Increase slippage for volatile tokens
"buy 0.01 SOL of TOKEN with 10% slippage"

# Decrease slippage for stable pairs
"swap 1 SOL to USDC with 0.5% slippage"

# Set global default
export DEFAULT_SLIPPAGE=5

Tool Execution Issues

Tool Not Found

Symptoms:

  • "Tool 'xyz' not found"
  • Agent can't execute requested action

Solutions:

# List available tools
sam tools

# Check agent initialization
sam health  # Verify tools loaded

# Restart agent
sam  # Fresh session

Rate Limit Exceeded

Symptoms:

  • "Rate limit exceeded"
  • API calls temporarily blocked

Solutions:

# Wait before retrying (rate limits reset every minute)
sleep 60

# Check rate limit status
sam health

# Reduce request frequency
export RATE_LIMITING_ENABLED=true

Tool Execution Timeout

Symptoms:

  • "Operation timed out"
  • Long-running operations fail

Solutions:

# Check network connectivity
ping api.mainnet-beta.solana.com

# Try different RPC endpoint
export SAM_SOLANA_RPC_URL="https://backup-rpc.com"

# Increase timeout (if configurable)
export HTTP_TIMEOUT=120

Memory & Performance Issues

High Memory Usage

Symptoms:

  • System slowdown
  • Out of memory errors

Solutions:

# Clear conversation context
sam
/clear-context

# Compact conversation history
/compact

# Check memory usage
sam health  # Shows memory stats

# Restart agent for fresh session
sam

Database Issues

Symptoms:

  • "Database locked"
  • "Corruption detected"

Solutions:

# Run maintenance
sam maintenance

# Check database integrity
sam health

# Backup and restore (if corruption)
cp .sam/sam_memory.db .sam/backup.db
sam  # Creates new database

Security Issues

Encryption Key Mismatch

Symptoms:

  • "Decryption failed"
  • Can't access stored private keys

Solutions:

# Verify encryption key matches stored data
echo $SAM_FERNET_KEY

# Re-import private key with current key
sam key import

# Generate new key and reconfigure
sam key generate
sam key import

Permission Errors

Symptoms:

  • "Permission denied" for keyring/database

Solutions:

# Fix file permissions
chmod 600 .env
chmod 700 .sam/

# Run with proper user permissions
# Don't run as root for security

🔧 Advanced Troubleshooting

Debug Mode

Enable detailed logging for investigation:

# Debug mode
sam --log-level DEBUG

# Check logs
tail -f sam.log

# Verbose health check
sam health --verbose

Network Diagnostics

# Test all API endpoints
curl -I https://api.openai.com/v1/models
curl -I $SAM_SOLANA_RPC_URL
curl -I https://api.search.brave.com/

# DNS resolution
nslookup api.mainnet-beta.solana.com

# Network latency
ping -c 3 api.mainnet-beta.solana.com

Configuration Validation

# Validate all settings
sam setup --verbose

# Check environment variables
env | grep -E "(OPENAI|SAM_|BRAVE)"

# Verify .env file syntax
python -c "import dotenv; dotenv.load_dotenv('.env'); print('Valid')"

Database Diagnostics

# Check database size
ls -lh .sam/sam_memory.db

# Verify database integrity
sqlite3 .sam/sam_memory.db "PRAGMA integrity_check;"

# View recent sessions
sqlite3 .sam/sam_memory.db "SELECT COUNT(*) FROM sessions;"

# Clear old data
sam maintenance

🚨 Critical Issues

Complete Data Loss

Symptoms:

  • Database corruption
  • All sessions lost
  • Configuration missing

Recovery:

# Backup current state
cp -r .sam .sam.backup

# Reinitialize
sam onboard  # Fresh setup

# Restore from backup if needed
cp .sam.backup/* .sam/

Security Breach

Symptoms:

  • Unauthorized transactions
  • Unknown API usage
  • Suspicious activity

Immediate Actions:

  1. Stop all operations
  2. Revoke API keys
  3. Change private keys
  4. Audit transaction history
  5. Report incident

System Compromise

Symptoms:

  • Unexpected behavior
  • Unknown processes
  • Modified files

Recovery:

# Isolate system
# Change all credentials
# Reinstall from trusted source
# Verify file integrity

📞 Getting Help

Support Resources

  1. Health Check First

    sam health  # Always run this first

  2. Gather Information

    sam setup    # Configuration status
sam --log-level DEBUG  # Enable debug logging

  3. Community Support

Information to Provide

When reporting issues, include:

# System information
python --version
uv --version
uname -a

# SAM version and status
sam --version  # If available
sam health

# Configuration (redact sensitive data)
sam setup

# Error logs
tail -50 sam.log

🛠️ Recovery Procedures

Factory Reset

# Complete reset (CAUTION: loses all data)
rm -rf .sam/
rm .env
sam onboard  # Fresh start

Partial Reset

# Reset specific components
sam key generate  # New encryption key
sam key import    # Re-import private key
sam maintenance   # Database cleanup

Backup and Restore

# Create backup
tar -czf sam_backup_$(date +%Y%m%d).tar.gz .sam/ .env

# Restore from backup
tar -xzf sam_backup_20231201.tar.gz

🚀 Prevention Tips

  • • Regular Health Checks: Run sam health daily
  • • Backup Configuration: Keep .env and .sam/ backed up
  • • Monitor Usage: Check API usage regularly
  • • Update Regularly: Keep SAM and dependencies updated
  • • Secure Environment: Don't share private keys or API keys
  • • Test Transactions: Use small amounts for testing