# Troubleshooting

This guide helps you diagnose and resolve common issues with Edison.

## Common Issues and Solutions

```mermaid
flowchart TB
    Start[Issue Detected] --> A{API Related?}
    A -->|Yes| B[API Issues]
    A -->|No| C{Installation Related?}
    C -->|Yes| D[Installation Issues]
    C -->|No| E{Command Related?}
    E -->|Yes| F[Command Issues]
    E -->|No| G[Other Issues]
    
    B --> B1[Check API Key]
    B --> B2[Check Network]
    B --> B3[Check Model Access]
    
    D --> D1[Check Python Version]
    D --> D2[Check Dependencies]
    D --> D3[Check PATH]
    
    F --> F1[Check Command Syntax]
    F --> F2[Check Shell Compatibility]
    
    style Start fill:#f9d5e5,stroke:#333,stroke-width:2px
    style B fill:#eeeeee,stroke:#333,stroke-width:2px
    style D fill:#d3f6db,stroke:#333,stroke-width:2px
    style F fill:#d3f6f5,stroke:#333,stroke-width:2px
    style G fill:#f5d3d3,stroke:#333,stroke-width:2px
```

### API Issues

| Issue | Solution |
|-------|----------|
| `No OpenAI API key found` | Set your API key using one of the [configuration methods](configuration.md#setting-your-openai-api-key) |
| `Rate limit exceeded` | Wait a minute before trying again, or check your OpenAI rate limits |
| `Invalid API key` | Verify your API key is correct and has not expired |
| `Model not available` | Ensure you have access to the requested model, or change to `gpt-3.5-turbo` |

### Installation Issues

| Issue | Solution |
|-------|----------|
| `Command not found: edison` | Ensure Edison is installed and in your PATH |
| `No module named 'openai'` | Reinstall Edison or run `pip install -r requirements.txt` |
| `ModuleNotFoundError` | Ensure all dependencies are installed correctly |
| `Python version error` | Ensure you're using Python 3.6+ |

### Command Execution Issues

| Issue | Solution |
|-------|----------|
| `Command contains markdown` | Edison detected markdown in the response; rerun the query |
| `Command execution failed` | The generated command has syntax errors; try modifying it |
| `Permission denied` | The command requires higher permissions; prefix with sudo if appropriate |
| `Command not found` | The generated command uses a program not installed on your system |

### Other Issues

| Issue | Solution |
|-------|----------|
| `Slow response times` | Try a faster model or check your internet connection |
| `Inaccurate commands` | Be more specific in your query or add more context |
| `Unexpected behavior` | Check the logs for detailed error information |

## Enabling Verbose Mode

For more detailed troubleshooting, use verbose mode:

```bash
edison -v your query here
```

This will print detailed logs that can help identify issues.

## Checking Logs

Log files are stored in the `edison/logs` directory. The main log file is `edison.log`. Check this file for detailed error messages and API interactions.

```bash
cat edison/logs/edison.log | tail -n 50
```

## Resetting Configuration

If you suspect a configuration issue, you can reset to defaults by removing or renaming your `edison.yaml` file:

```bash
mv edison.yaml edison.yaml.bak
```

Edison will create a new configuration file with default settings on the next run.

## Common Error Messages and Meanings

### "No OpenAI API key found"

You need to set your OpenAI API key. See [configuration options](configuration.md).

### "Error calling OpenAI API"

There was an issue communicating with the OpenAI API. Check:
1. Your internet connection
2. API key validity
3. OpenAI service status

### "Response does not contain a valid command"

The AI generated a response that Edison couldn't interpret as a command. Try:
1. Rephrasing your query to be more specific
2. Checking logs for the full response
3. Using a different model

## Getting Help

If you continue to experience issues:

1. Check the full documentation
2. Look for similar issues in the GitHub repository
3. Open a new issue with:
   - A clear description of the problem
   - Steps to reproduce
   - Any error messages (with sensitive information redacted)
   - Your OS and Python version