128 lines
4.0 KiB
Markdown
128 lines
4.0 KiB
Markdown
# 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 |