Resources
Troubleshooting Guide
Common issues and solutions for RunAgent
Installation Issues
Solution: Install with user flag or use virtual environment
Copy
# User installation
pip install --user runagent
# Or use virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install runagent
Solution: Add Python scripts to PATH or use python -m
Copy
# Check where it's installed
pip show runagent
# Use python module directly
python -m runagent --help
# Add to PATH (Linux/Mac)
export PATH="$PATH:$HOME/.local/bin"
# Add to PATH (Windows)
set PATH=%PATH%;%APPDATA%\Python\Scripts
Solution: Update certificates or use trusted host
Copy
# Update certificates
pip install --upgrade certifi
# Or temporarily bypass (not recommended for production)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org runagent
Configuration Issues
Common causes and solutions:
-
JSON syntax error
Copy# Validate JSON python -m json.tool runagent.config.json -
Missing required fields
Copy{ "agent_name": "required", "framework": "required", "version": "required", "agent_architecture": { "entrypoints": [...] // required } } -
Invalid entrypoint path
Copy# Test import manually python -c "from agents import app; print(app.invoke)"
Solution: Check .env file and loading mechanism
Copy
# Ensure .env exists
ls -la .env
# Check format (no spaces around =)
OPENAI_API_KEY=sk-...
NOT: OPENAI_API_KEY = sk-...
# Load manually in Python
from dotenv import load_dotenv
load_dotenv()
Local Development Issues
Solution: Find and kill process or use different port
Copy
# Find process (Linux/Mac)
lsof -i :8000
kill -9 <PID>
# Find process (Windows)
netstat -ano | findstr :8000
taskkill /PID <PID> /F
# Or use different port
runagent serve . --port 8080
Solution: Check dependencies and Python path
Copy
# Install all dependencies
pip install -r requirements.txt
# Check Python path
python -c "import sys; print(sys.path)"
# Add current directory to PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:."
Solution: Check file watchers and restart manually
Copy
# Check if reload is enabled
runagent serve . --reload
# Touch file to trigger reload
touch agent.py
# Check system file watchers limit (Linux)
cat /proc/sys/fs/inotify/max_user_watches
# Increase if needed
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
Runtime Errors
Solution: Increase timeout or optimize agent code
Copy
# In runagent.config.json
{
"deployment": {
"timeout": 60 // Increase from default 30s
}
}
# Optimize agent code
# - Cache expensive operations
# - Use async where possible
# - Reduce external API calls
Solution: Increase memory limit or reduce usage
Copy
{
"deployment": {
"memory": "1GB" // Increase from default 512MB
}
}
Tips for reducing memory:
- Load models once, not per request
- Use generators for large datasets
- Clear unused variables
- Profile memory usage
Common issues:
-
Key not found
Copy# Check environment echo $OPENAI_API_KEY # Set in .env file OPENAI_API_KEY=sk-... -
Invalid key format
- OpenAI keys start with
sk- - No extra spaces or quotes
- Check expiration
- OpenAI keys start with
-
Rate limits
- Implement retry logic
- Use different keys for dev/prod
- Monitor usage
Deployment Issues
Solution: Run validation locally first
Copy
# Validate configuration
runagent validate .
# Test imports
runagent test-import .
# Check file sizes
find . -size +10M -type f
Debugging steps:
Copy
# Check status
runagent status <deployment-id>
# View logs
runagent logs <deployment-id> --tail 100
# Test health endpoint
curl https://api.run-agent.ai/v1/agents/<id>/health
# Restart if needed
runagent restart <deployment-id>
SDK Issues
Solution: Check API key configuration
Copy
# Debug authentication
import os
print(f"API Key present: {'RUNAGENT_API_KEY' in os.environ}")
# Explicit configuration
from runagent import RunAgentClient
client = RunAgentClient(
agent_id="...",
api_key="your-key-here",
debug=True # Enable debug logging
)
Common causes:
-
Buffering issues
Copy# Force unbuffered output for chunk in client.run_generic_stream(input_data): print(chunk, end="", flush=True) -
Proxy interference
- Check if behind corporate proxy
- Test with direct connection
- Use appropriate proxy settings
Performance Issues
Optimization strategies:
-
Profile your code
Copyimport time start = time.time() # Your operation print(f"Operation took: {time.time() - start}s") -
Cache expensive operations
Copyfrom functools import lru_cache @lru_cache(maxsize=100) def expensive_operation(input): # Cache results return result -
Use connection pooling
Copy# Reuse HTTP sessions import requests session = requests.Session()
Memory optimization:
Copy
# Use generators instead of lists
def process_large_data():
for item in data:
yield process(item) # Not return all at once
# Clear unused objects
del large_object
import gc
gc.collect()
# Monitor memory
import psutil
print(f"Memory: {psutil.Process().memory_info().rss / 1024 / 1024} MB")
Debugging Tools
Enable Debug Logging
Copy
# In your agent
import logging
logging.basicConfig(level=logging.DEBUG)
# For RunAgent CLI
runagent serve . --log-level debug
# For SDK
client = RunAgentClient(agent_id="...", debug=True)
Health Checks
Copy
# Add health check endpoint
def health_check():
checks = {
"status": "healthy",
"database": check_database(),
"api_keys": check_api_keys(),
"memory": check_memory()
}
return checks
Performance Monitoring
Copy
# Simple performance decorator
import time
from functools import wraps
def measure_time(func):
@wraps(func)
def wrapper(*args, **kwargs):
start = time.time()
result = func(*args, **kwargs)
print(f"{func.__name__} took {time.time() - start:.2f}s")
return result
return wrapper
@measure_time
def slow_operation():
# Your code
pass
Getting Help
If you’re still experiencing issues:
Discord Community
Get help from the community
GitHub Issues
Report bugs or request features
Email Support
For critical issues
Status Page
Check system status
Diagnostic Commands
Quick commands for diagnosing issues:
Copy
# System check
runagent doctor
# Validate project
runagent validate . --verbose
# Test connectivity
runagent ping
# Export debug info
runagent debug-info > debug.txt
Assistant
Responses are generated using AI and may contain mistakes.