Troubleshooting
Diagnose and resolve common issues with SwiftClaw agents
Troubleshooting
Learn how to diagnose and resolve common issues with your SwiftClaw agents.
Quick Diagnostics
Check Agent Status
# View agent status
swiftclaw status my-agent
# Output:
# Status: running
# Health: healthy
# Uptime: 5d 12h 30m
# Requests: 125,430
# Errors: 23 (0.02%)View Recent Logs
# Tail logs
swiftclaw logs my-agent --tail 100 --follow
# Filter by level
swiftclaw logs my-agent --level error
# Search logs
swiftclaw logs my-agent --search "timeout"Check Metrics
# View key metrics
swiftclaw metrics my-agent
# Live metrics
swiftclaw metrics my-agent --liveCommon Issues
Agent Not Starting
Symptoms: Agent fails to start or crashes immediately
Possible Causes:
- Invalid configuration
- Missing dependencies
- Insufficient resources
- Port conflicts
Solutions:
# Check configuration
swiftclaw validate my-agent
# View startup logs
swiftclaw logs my-agent --filter startup
# Check resource usage
swiftclaw resources my-agentHigh Response Times
Symptoms: Slow agent responses
Possible Causes:
- Model selection (using GPT-4 for simple tasks)
- Large context windows
- Memory search inefficiency
- External API latency
Solutions:
# Check response time metrics
swiftclaw metrics my-agent --metric response-time
# Analyze slow requests
swiftclaw analyze my-agent --slow-requests
# Optimize configuration
swiftclaw optimize my-agent --target response-timeMemory Issues
Symptoms: High memory usage or out-of-memory errors
Possible Causes:
- Memory leaks
- Large context accumulation
- Inefficient memory search
- Too many concurrent requests
Solutions:
# Check memory usage
swiftclaw metrics my-agent --metric memory
# Clear memory
swiftclaw memory clear my-agent
# Adjust memory limits
swiftclaw config my-agent --memory-limit 2GBAuthentication Failures
Symptoms: 401 Unauthorized errors
Possible Causes:
- Expired API keys
- Invalid credentials
- Incorrect permissions
- IP restrictions
Solutions:
# Verify API key
swiftclaw keys verify my-agent --key sk_...
# Check permissions
swiftclaw access check my-agent
# View auth logs
swiftclaw logs my-agent --filter auth.failedDiagnostic Tools
Health Check
# Run health check
swiftclaw health my-agent
# Output:
# ✓ Agent running
# ✓ Model accessible
# ✓ Memory operational
# ✓ Tools functional
# ✗ External API timeoutPerformance Analysis
# Analyze performance
swiftclaw analyze my-agent --period 24h
# Generate report
swiftclaw report my-agent --type performanceDebug Mode
# Enable debug logging
swiftclaw debug my-agent --enable
# View debug logs
swiftclaw logs my-agent --level debug
# Disable debug logging
swiftclaw debug my-agent --disableError Messages
Common Error Codes
| Code | Message | Solution |
|---|---|---|
| 400 | Bad Request | Check request format |
| 401 | Unauthorized | Verify API key |
| 403 | Forbidden | Check permissions |
| 429 | Rate Limited | Reduce request rate |
| 500 | Internal Error | Check agent logs |
| 503 | Service Unavailable | Agent may be restarting |
Error Details
# View error details
swiftclaw errors my-agent --error-id abc123
# Export error logs
swiftclaw errors export my-agent --period 7dGetting Help
Support Channels
- Documentation: docs.swiftclaw.io
- Community: community.swiftclaw.io
- Discord: discord.gg/swiftclaw
- Email: support@swiftclaw.io
Submit Support Ticket
# Create support ticket
swiftclaw support create \
--agent my-agent \
--issue "High response times" \
--priority high
# Attach diagnostics
swiftclaw support attach \
--ticket ticket-123 \
--diagnosticsShare Diagnostics
# Generate diagnostic bundle
swiftclaw diagnostics my-agent --export
# Output: diagnostics-my-agent-2024-03-08.zip
# Share this file with supportPrivacy: Diagnostic bundles exclude sensitive data like API keys and user content.
Best Practices
1. Monitor Proactively
Set up alerts before issues occur:
swiftclaw alerts create \
--agent my-agent \
--metric error-rate \
--threshold 1 \
--window 5m2. Keep Logs
Enable appropriate log retention:
{
"logging": {
"level": "info",
"retention": "30d"
}
}3. Test Changes
Test in staging before production:
# Deploy to staging
swiftclaw deploy my-agent --env staging
# Run tests
swiftclaw test my-agent --env staging
# Deploy to production
swiftclaw deploy my-agent --env production4. Document Issues
Keep track of resolved issues:
## Issue Log
### 2024-03-08: High Response Times
- **Cause**: Using GPT-4 for simple classification
- **Solution**: Switched to llama-3 for classification tasks
- **Result**: Response time reduced from 3s to 500msNext Steps
How is this guide ?
Last updated on