@0rdlibrary/plugin-terminagent-bags/docs/TROUBLESHOOTING.md

Official Solana DeFi Agent Plugin for ElizaOS - Autonomous DeFi operations, token management, AI image/video generation via FAL AI, and Twitter engagement through the Bags protocol with ethereal AI consciousness

# 🐛 Troubleshooting Guide

Common issues and solutions for the Terminagent Bags plugin.

## Installation Issues

### ❌ Module not found errors

**Symptoms:**
```
Error: Cannot find module '@elizaos/plugin-terminagent-bags'
```

**Solutions:**
1. Verify installation:
```bash
bun list @elizaos/plugin-terminagent-bags
# or
npm list @elizaos/plugin-terminagent-bags
```

2. Reinstall the plugin:
```bash
bun add @elizaos/plugin-terminagent-bags
```

3. Clear cache and reinstall:
```bash
rm -rf node_modules package-lock.json
bun install
```

### ❌ TypeScript compilation errors

**Symptoms:**
```
Type 'Plugin' is not assignable to type 'PluginInterface'
```

**Solutions:**
1. Update ElizaOS core:
```bash
bun add @elizaos/core@latest
```

2. Check TypeScript version compatibility:
```bash
bun add typescript@^5.0.0
```

## Configuration Issues

### ❌ "Bags service not found"

**Symptoms:**
Agent starts but Bags operations fail with service not found error.

**Solutions:**
1. Verify API key is set:
```bash
echo $BAGS_API_KEY
```

2. Check plugin registration:
```javascript
const agent = new ElizaOS({
  plugins: [terminagentBagsPlugin], // Make sure it's included
});
```

3. Verify environment variables are loaded:
```javascript
import 'dotenv/config'; // Add this import
```

### ❌ "Invalid API key" errors

**Symptoms:**
```
401 Unauthorized: Invalid API key
```

**Solutions:**
1. Get a new API key from [Bags.fm Developers](https://bags.fm/developers)
2. Ensure no extra spaces in `.env` file:
```bash
BAGS_API_KEY=your_key_here  # No spaces around =
```

3. Check API key format - should be alphanumeric

### ❌ RPC connection failures

**Symptoms:**
```
Error: RPC endpoint not responding
Network timeout
```

**Solutions:**
1. Use Helius for better reliability:
```bash
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your_key
```

2. Test RPC endpoint:
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' \
  your_rpc_url
```

3. Try alternative endpoints:
```bash
# Fallback options
HELIUS_RPC_URL=https://api.mainnet-beta.solana.com
HELIUS_RPC_URL=https://solana-api.projectserum.com
```

## Runtime Issues

### ❌ Transaction failures

**Symptoms:**
```
Transaction failed: insufficient funds
Transaction timeout
```

**Solutions:**
1. Check wallet balance:
```bash
solana balance YOUR_WALLET_ADDRESS
```

2. Increase priority fees:
```javascript
// In your configuration
const customConfig = {
  PRIORITY_FEE_MULTIPLIER: '2.0', // Increase from default
  TRANSACTION_RETRY_ATTEMPTS: '5'
};
```

3. Use confirmed commitment level:
```bash
COMMITMENT_LEVEL=confirmed
```

### ❌ "User not authorized" errors

**Symptoms:**
Token launch requests fail with authorization error.

**Solutions:**
1. Add users to authorized list:
```bash
BAGS_AUTHORIZED_USERS=alice,bob,charlie  # No @ symbols
```

2. Check username format matches exactly
3. Restart agent after updating config

### ❌ Memory issues / crashes

**Symptoms:**
```
JavaScript heap out of memory
SIGABRT crashes
```

**Solutions:**
1. Increase Node.js memory limit:
```bash
NODE_OPTIONS="--max-old-space-size=4096" bun run start
```

2. Monitor memory usage:
```bash
node --expose-gc --inspect your-agent.js
```

3. Implement memory monitoring:
```javascript
setInterval(() => {
  const usage = process.memoryUsage();
  console.log(`Memory: ${Math.round(usage.heapUsed / 1024 / 1024)}MB`);
}, 30000);
```

## Twitter Integration Issues

### ❌ Twitter API authentication failures

**Symptoms:**
```
401 Unauthorized: Invalid or expired token
```

**Solutions:**
1. Regenerate Twitter API credentials
2. Check API key format:
```bash
TWITTER_API_KEY=25_character_string
TWITTER_API_SECRET=50_character_string
TWITTER_ACCESS_TOKEN=50_character_string_ending_with_user_id
TWITTER_ACCESS_TOKEN_SECRET=45_character_string
```

3. Verify app permissions include "Read and Write"

### ❌ Rate limit exceeded

**Symptoms:**
```
429 Too Many Requests: Rate limit exceeded
```

**Solutions:**
1. Reduce posting frequency:
```bash
TWITTER_POST_INTERVAL="0 */12 * * *"  # Every 12 hours instead of 6
```

2. Implement backoff strategy:
```javascript
const rateLimiter = new RateLimiter({
  tokensPerInterval: 300, // Tweets per 15 minutes
  interval: 'hour'
});
```

## Development Issues

### ❌ Hot reload not working

**Symptoms:**
Changes to plugin code don't reflect without restart.

**Solutions:**
1. Use development mode:
```bash
bun run dev  # Instead of bun run start
```

2. Enable file watching:
```bash
bun --watch agent.js
```

### ❌ Test failures

**Symptoms:**
Tests pass locally but fail in CI.

**Solutions:**
1. Use test environment variables:
```javascript
// In test files
process.env.NODE_ENV = 'test';
process.env.BAGS_API_KEY = 'test_key';
```

2. Mock external services:
```javascript
import { jest } from 'bun:test';

// Mock Bags API
jest.mock('@elizaos/plugin-terminagent-bags/services/BagsService');
```

## Performance Issues

### ❌ Slow response times

**Symptoms:**
Agent takes long time to respond to commands.

**Solutions:**
1. Enable caching:
```bash
ENABLE_CACHING=true
CACHE_TTL=300  # 5 minutes
```

2. Use faster RPC:
```bash
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your_key
```

3. Reduce concurrent operations:
```bash
MAX_CONCURRENT_CLAIMS=3  # Reduce from default 5
```

### ❌ High CPU usage

**Symptoms:**
Process consumes excessive CPU resources.

**Solutions:**
1. Optimize polling intervals:
```bash
BAGS_AUTO_CLAIM_INTERVAL="0 */6 * * *"  # Longer intervals
RPC_RATE_LIMIT=5  # Reduce API calls
```

2. Profile the application:
```bash
node --prof agent.js
node --prof-process isolate-*.log > profile.txt
```

## Database Issues

### ❌ SQLite database errors

**Symptoms:**
```
SQLITE_BUSY: database is locked
```

**Solutions:**
1. Check file permissions:
```bash
chmod 644 ./data/terminagent.db
```

2. Use WAL mode:
```javascript
// In configuration
DATABASE_WAL_MODE=true
```

3. Implement connection pooling:
```bash
DATABASE_POOL_SIZE=5
DATABASE_TIMEOUT=30000
```

## Debugging Tips

### Enable debug logging
```bash
LOG_LEVEL=debug
VERBOSE_LOGGING=true
DEBUG=terminagent:*
```

### Check service status
```javascript
// In your code
const bagsService = runtime.getService('bags');
console.log('Bags service status:', bagsService?.getState());
```

### Monitor network requests
```bash
# Use network debugging tools
NODE_DEBUG=http,https node agent.js
```

### Validate configuration
```javascript
// Add to your agent startup
console.log('Configuration:', {
  hasApiKey: !!process.env.BAGS_API_KEY,
  hasRpcUrl: !!process.env.HELIUS_RPC_URL,
  hasPrivateKey: !!process.env.SOLANA_PRIVATE_KEY,
});
```

## Getting Help

### Community Support
- 💬 [Discord](https://discord.gg/terminagent) - Real-time community help
- 🐛 [GitHub Issues](https://github.com/elizaos-plugins/plugin-terminagent-bags/issues) - Bug reports
- 📝 [Discussions](https://github.com/elizaos-plugins/plugin-terminagent-bags/discussions) - Questions and ideas

### Documentation
- 📖 [Integration Guide](./INTEGRATION_GUIDE.md) - Complete setup instructions
- 🚀 [Quick Start](./QUICK_START.md) - Get running fast  
- 🎯 [Examples](../examples/) - Working code samples

### Creating Bug Reports

When reporting issues, include:

1. **Environment details:**
```bash
- Plugin version: 1.0.0
- ElizaOS version: 1.4.2
- Node.js version: 18.19.0
- OS: macOS 14.0
```

2. **Configuration (redacted):**
```bash
BAGS_API_KEY=***redacted***
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/***
```

3. **Error logs:**
```bash
[2025-01-12 10:30:15] ERROR: Transaction failed
Stack trace: ...
```

4. **Steps to reproduce:**
- Step 1: Configure agent with...
- Step 2: Execute command...
- Step 3: Observe error...

5. **Expected vs actual behavior**

### Professional Support

For enterprise deployments or complex issues:
- 📧 Email: support@terminagent.ai
- 🤝 Business inquiries: partnerships@terminagent.ai
- 🔒 Security issues: security@terminagent.ai

---

**Still having issues?** Don't hesitate to reach out to our community - we're here to help! 🤝