> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run-agent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Common issues and solutions for RunAgent

## Installation Issues

<AccordionGroup>
  <Accordion title="pip install fails with permission error">
    **Solution**: Install with user flag or use virtual environment

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="runagent command not found after installation">
    **Solution**: Add Python scripts to PATH or use python -m

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="SSL certificate verification failed">
    **Solution**: Update certificates or use trusted host

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

## Configuration Issues

<AccordionGroup>
  <Accordion title="Invalid runagent.config.json">
    **Common causes and solutions**:

    1. **JSON syntax error**
       ```bash theme={null}
       # Validate JSON
       python -m json.tool runagent.config.json
       ```

    2. **Missing required fields**
       ```json theme={null}
       {
         "agent_name": "required",
         "framework": "required",
         "version": "required",
         "agent_architecture": {
           "entrypoints": [...]  // required
         }
       }
       ```

    3. **Invalid entrypoint path**
       ```bash theme={null}
       # Test import manually
       python -c "from agents import app; print(app.invoke)"
       ```
  </Accordion>

  <Accordion title="Environment variables not loading">
    **Solution**: Check .env file and loading mechanism

    ```bash theme={null}
    # 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()
    ```
  </Accordion>
</AccordionGroup>

## Local Development Issues

<AccordionGroup>
  <Accordion title="Port already in use">
    **Solution**: Find and kill process or use different port

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Module import errors">
    **Solution**: Check dependencies and Python path

    ```bash theme={null}
    # 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}:."
    ```
  </Accordion>

  <Accordion title="Hot reload not working">
    **Solution**: Check file watchers and restart manually

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

## Runtime Errors

<AccordionGroup>
  <Accordion title="Agent timeout errors">
    **Solution**: Increase timeout or optimize agent code

    ```python theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Memory limit exceeded">
    **Solution**: Increase memory limit or reduce usage

    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="API key errors">
    **Common issues**:

    1. **Key not found**
       ```bash theme={null}
       # Check environment
       echo $OPENAI_API_KEY

       # Set in .env file
       OPENAI_API_KEY=sk-...
       ```

    2. **Invalid key format**
       * OpenAI keys start with `sk-`
       * No extra spaces or quotes
       * Check expiration

    3. **Rate limits**
       * Implement retry logic
       * Use different keys for dev/prod
       * Monitor usage
  </Accordion>
</AccordionGroup>

## Deployment Issues

<AccordionGroup>
  <Accordion title="Deployment fails validation">
    **Solution**: Run validation locally first

    ```bash theme={null}
    # Validate configuration
    runagent validate .

    # Test imports
    runagent test-import .

    # Check file sizes
    find . -size +10M -type f
    ```
  </Accordion>

  <Accordion title="Agent not responding after deployment">
    **Debugging steps**:

    ```bash theme={null}
    # 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>
    ```
  </Accordion>
</AccordionGroup>

## SDK Issues

<AccordionGroup>
  <Accordion title="Authentication errors with SDK">
    **Solution**: Check API key configuration

    ```python theme={null}
    # 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
    )
    ```
  </Accordion>

  <Accordion title="Streaming not working">
    **Common causes**:

    1. **Buffering issues**
       ```python theme={null}
       # Force unbuffered output
       for chunk in client.run_generic_stream(input_data):
           print(chunk, end="", flush=True)
       ```

    2. **Proxy interference**
       * Check if behind corporate proxy
       * Test with direct connection
       * Use appropriate proxy settings
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="Slow agent response times">
    **Optimization strategies**:

    1. **Profile your code**
       ```python theme={null}
       import time

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

    2. **Cache expensive operations**
       ```python theme={null}
       from functools import lru_cache

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

    3. **Use connection pooling**
       ```python theme={null}
       # Reuse HTTP sessions
       import requests
       session = requests.Session()
       ```
  </Accordion>

  <Accordion title="High memory usage">
    **Memory optimization**:

    ```python theme={null}
    # 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")
    ```
  </Accordion>
</AccordionGroup>

## Debugging Tools

### Enable Debug Logging

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord">
    Get help from the community

    [Join Discord →](https://discord.gg/runagent)
  </Card>

  <Card title="GitHub Issues" icon="github">
    Report bugs or request features

    [Open Issue →](https://github.com/runagent-dev/runagent/issues)
  </Card>

  <Card title="Email Support" icon="envelope">
    For critical issues

    [support@run-agent.ai](mailto:support@run-agent.ai)
  </Card>

  <Card title="Status Page" icon="signal">
    Check system status

    [View Status →](https://status.run-agent.ai)
  </Card>
</CardGroup>

## Diagnostic Commands

Quick commands for diagnosing issues:

```bash theme={null}
# System check
runagent doctor

# Validate project
runagent validate . --verbose

# Test connectivity
runagent ping

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