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

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

Get Started

Frameworks

Configuration Overview

Deployment

Resources

Troubleshooting Guide

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

Discord Community

GitHub Issues

Email Support

Status Page

Diagnostic Commands

Get Started

Frameworks

Configuration Overview

Deployment

Resources

​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

Discord Community

GitHub Issues

Email Support

Status Page

​Diagnostic Commands

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

Diagnostic Commands