command-assistant/docs/user/troubleshooting.md

Troubleshooting

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

Common Issues and Solutions

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
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:

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.

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:

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.

"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