Troubleshooting Guide

Installation Issues

pip install fails with permission error

Solution: Install with user flag or use virtual environment

# 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

runagent command not found after installation

Solution: Add Python scripts to PATH or use python -m

# 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

SSL certificate verification failed

Solution: Update certificates or use trusted host

# 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

Invalid runagent.config.json

Common causes and solutions:

JSON syntax error

# Validate JSON
python -m json.tool runagent.config.json

Missing required fields

{
  "agent_name": "required",
  "framework": "required",
  "version": "required",
  "agent_architecture": {
    "entrypoints": [...]  // required
  }
}

Invalid entrypoint path

# Test import manually
python -c "from agents import app; print(app.invoke)"

Environment variables not loading

Solution: Check .env file and loading mechanism

# 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

Port already in use

Solution: Find and kill process or use different port

# 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

Module import errors

Solution: Check dependencies and Python path

# 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}:."

Hot reload not working

Solution: Check file watchers and restart manually

# 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

Agent timeout errors

Solution: Increase timeout or optimize agent code

# 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

Memory limit exceeded

Solution: Increase memory limit or reduce usage

{
  "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

API key errors

Common issues:

Key not found

# 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
Rate limits
- Implement retry logic
- Use different keys for dev/prod
- Monitor usage

Deployment Issues

Deployment fails validation

Solution: Run validation locally first

# Validate configuration
runagent validate .

# Test imports
runagent test-import .

# Check file sizes
find . -size +10M -type f

Agent not responding after deployment

Debugging steps:

# 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

Authentication errors with SDK

Solution: Check API key configuration

# 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
)

Streaming not working

Common causes:

Buffering issues

# 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

Slow agent response times

Optimization strategies:

Profile your code

import time

start = time.time()
# Your operation
print(f"Operation took: {time.time() - start}s")

Cache expensive operations

from functools import lru_cache

@lru_cache(maxsize=100)
def expensive_operation(input):
    # Cache results
    return result

Use connection pooling

# Reuse HTTP sessions
import requests
session = requests.Session()

High memory usage

Memory optimization:

# 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

# 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

# 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

# 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 communityJoin Discord →

GitHub Issues

Report bugs or request featuresOpen Issue →

Email Support

For critical issues[email protected]

Status Page

Check system statusView Status →

Diagnostic Commands

Quick commands for diagnosing issues:

# System check
runagent doctor

# Validate project
runagent validate . --verbose

# Test connectivity
runagent ping

# Export debug info
runagent debug-info > debug.txt

​Installation Issues

​Configuration Issues

​Local Development Issues

​Runtime Errors

​Deployment Issues

​SDK Issues

​Performance Issues

​Debugging Tools

​Enable Debug Logging

​Health Checks

​Performance Monitoring

​Getting Help