Skip to main content

​
Troubleshooting

This guide covers common issues you might encounter when building and deploying Erdo agents, along with solutions and debugging techniques.

​
Common Issues

​
Authentication Problems

Symptoms:
  • erdo login fails with authentication error
  • “Invalid credentials” message
  • Cannot access platform features
Solutions:
# Clear auth cache and retry
rm ~/.erdo/auth.json
erdo login --force

# Check server configuration
erdo configure --show

# Test connectivity
curl -I https://api.erdo.ai/health
Symptoms:
  • “Token expired” errors
  • “Unauthorized” API responses
  • Commands work intermittently
Solutions:
# Refresh authentication
erdo login --force

# Check token status
erdo whoami --verbose

# Verify token permissions
erdo token list

​
Development Issues

Symptoms:
  • erdo dev fails to start
  • Deployment errors
  • Agent not responding
Debugging steps:
# Check agent syntax
erdo introspect my-agent --validate

# Test locally
erdo test --agent my-agent --verbose

# Check logs
erdo logs my-agent --level error --since 1h

# Validate configuration
erdo deploy my-agent --validate-only
Symptoms:
  • Steps fail unexpectedly
  • Timeout errors
  • Memory/resource issues
Solutions:
# Increase timeouts
erdo configure --timeout 300

# Check resource usage
erdo monitor my-agent --metrics memory,cpu

# Test individual steps
erdo test --agent my-agent --step failing-step

# Enable debug mode
erdo dev --debug --verbose

​
Performance Issues

Symptoms:
  • Agents take too long to complete
  • High latency responses
  • Resource exhaustion
Optimization strategies:
# Use parallel execution
parallel_steps = [step1, step2, step3]
# No dependencies = parallel execution

# Cache expensive operations
cache_step = agent.step(
    memory.search(
        query="{{query}}",
        cache_ttl=3600  # 1 hour cache
    )
)

# Optimize LLM calls
efficient_llm = llm.message(
    model="claude-haiku",  # Faster model for simple tasks
    query="{{simple_query}}"
)
Solutions:
# Check storage usage
erdo monitor --metrics storage

# Clean up old data
erdo cache clear

# Optimize memory usage
erdo configure --memory-limit 2GB

​
Debugging Techniques

​
Logging and Monitoring

# Real-time log monitoring
erdo logs my-agent --follow --level debug

# Performance analysis
erdo monitor my-agent --metrics execution_time,memory,cpu

# Error pattern analysis
erdo logs my-agent --analyze-errors --since 7d

# Generate diagnostic report
erdo introspect my-agent --performance --output report.html

​
Testing Strategies

# Unit test individual steps
erdo test --type unit --agent my-agent --step specific-step

# Integration testing
erdo test --type integration --env staging

# Load testing
erdo test --parallel 10 --iterations 100

# Mock external dependencies
erdo test --mock-llm --mock-apis --agent my-agent

​
Development Best Practices

Error Handling

Always implement proper error handling and fallbacks in your agents

Monitoring

Use built-in monitoring and logging for production agents

Testing

Test thoroughly in staging before production deployment

Documentation

Document your agents and their expected behavior

​
Getting Help

​
Community Resources

​
Support Channels

  • GitHub for bug reports and questions - Stack Overflow for development questions

​
Diagnostic Information

When reporting issues, include: 
# System information
erdo version
erdo configure --show

# Error logs
erdo logs my-agent --level error --since 24h

# Agent configuration
erdo introspect my-agent --schema