Getting Started
Troubleshooting
Common issues and solutions for AI Developer Assistant
Troubleshooting
This guide covers common issues you might encounter when using AI Developer Assistant and their solutions.
Installation Issues
Command Not Found
Problem: ai-dev command is not recognized
bash: ai-dev: command not found
Solutions:
- Check if installed globally:
npm list -g kg6-codex
- Reinstall globally:
npm install -g kg6-codex
- Check PATH:
echo $PATH
which ai-dev
- Use npx instead:
npx ai-dev --help
Permission Denied
Problem: Permission errors when running commands
EACCES: permission denied, access '/usr/local/lib/node_modules'
Solutions:
- Fix npm permissions:
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
- Use npx:
npx ai-dev review
- Install locally:
npm install kg6-codex
./node_modules/.bin/ai-dev review
Configuration Issues
No LLM Provider Available
Problem: Error when trying to use AI features
Error: No LLM provider configured
Solutions:
- Check configuration:
ai-dev config show
- Set environment variables:
export LLM_PROVIDER="gemini"
export GEMINI_API_KEY="your-api-key"
- Create configuration file:
cp ai-dev.config.yaml ai-dev.config.local.yaml
# Edit with your settings
- Use CLI options:
ai-dev review --llm-provider openai --openai-api-key your-key
Invalid API Key
Problem: API key authentication fails
Error: Invalid API key provided
Solutions:
- Verify API key:
# Test OpenAI
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models
# Test Gemini
curl -H "x-goog-api-key: $GEMINI_API_KEY" https://generativelanguage.googleapis.com/v1beta/models
- Check key format:
- OpenAI: Should start with
sk- - Gemini: Should start with
AIza
- OpenAI: Should start with
- Regenerate API key:
- OpenAI: Platform Keys
- Gemini: AI Studio
Configuration File Errors
Problem: YAML syntax errors in configuration
Error: Invalid YAML syntax in ai-dev.config.local.yaml
Solutions:
- Validate YAML syntax:
ai-dev config validate
- Check indentation:
- Use 2 spaces (not tabs)
- Maintain consistent indentation
- Reset configuration:
cp ai-dev.config.yaml ai-dev.config.local.yaml
Git Integration Issues
Git Repository Not Found
Problem: Git operations fail
Error: Not a git repository
Solutions:
- Initialize git repository:
git init
- Navigate to git repository:
cd /path/to/your/git/repo
- Specify repository path:
ai-dev review --git-repo-path /path/to/repo
Git Authentication Issues
Problem: GitHub integration fails
Error: Git authentication failed
Solutions:
- Set GitHub token:
export GITHUB_TOKEN="your-github-token"
- Configure git credentials:
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
- Use SSH instead of HTTPS:
git remote set-url origin git@github.com:user/repo.git
LLM Provider Issues
OpenAI API Issues
Problem: OpenAI API errors
Error: OpenAI API request failed
Solutions:
- Check API key and organization:
export OPENAI_API_KEY="your-key"
export OPENAI_ORGANIZATION="your-org-id" # if applicable
- Check rate limits:
- Wait before retrying
- Check your OpenAI usage limits
- Try different model:
ai-dev review --llm-model gpt-3.5-turbo
Ollama Connection Issues
Problem: Cannot connect to Ollama
Error: Cannot connect to Ollama at http://localhost:11434
Solutions:
- Start Ollama service:
ollama serve
- Check if Ollama is running:
curl http://localhost:11434/api/tags
- Pull a model:
ollama pull llama2
- Check port:
ai-dev review --ollama-base-url http://localhost:11434
Gemini API Issues
Problem: Gemini API errors
Error: Gemini API request failed
Solutions:
- Check API key:
export GEMINI_API_KEY="your-key"
- Verify model availability:
ai-dev review --llm-model gemini-pro
- Check quota limits:
- Visit Google AI Studio
- Check your usage limits
File Pattern Issues
No Files Found
Problem: File patterns don't match any files
Warning: No files found matching pattern
Solutions:
- Check current directory:
pwd
ls -la
- Use absolute paths:
ai-dev review --file-patterns "/absolute/path/to/files/**/*.ts"
- Check pattern syntax:
# Correct patterns
ai-dev review --file-patterns "src/**/*.ts"
ai-dev review --file-patterns "*.{js,ts,jsx,tsx}"
Permission Denied on Files
Problem: Cannot read files
Error: Permission denied reading file
Solutions:
- Check file permissions:
ls -la filename
chmod 644 filename
- Run with appropriate user:
sudo -u your-user ai-dev review
Output Issues
No Output Generated
Problem: Commands run but produce no output
Solutions:
- Enable verbose mode:
ai-dev review --verbose
- Check file content:
ai-dev review --file-patterns "test-file.js"
- Use different output format:
ai-dev review --output-format json
Output Format Issues
Problem: Output formatting errors
Error: Invalid output format
Solutions:
- Use supported formats:
ai-dev review --output-format console
ai-dev review --output-format markdown
ai-dev review --output-format json
- Check file permissions for output:
ai-dev review --output-path /path/to/output.md
Performance Issues
Slow Response Times
Problem: Commands take too long to complete
Solutions:
- Use smaller file patterns:
ai-dev review --file-patterns "src/utils/**/*.ts" # Instead of "src/**/*.ts"
- Exclude large directories:
ai-dev review --exclude-patterns "node_modules/**,dist/**,build/**"
- Use faster models:
ai-dev review --llm-model gpt-3.5-turbo # Instead of gpt-4
Memory Issues
Problem: Out of memory errors
Solutions:
- Process smaller files:
ai-dev review --file-patterns "src/**/*.ts" --exclude-patterns "**/*.min.js"
- Increase Node.js memory:
node --max-old-space-size=4096 $(which ai-dev) review
Getting Help
Debug Information
When reporting issues, include:
# Version information
ai-dev --version
node --version
npm --version
# Configuration (without sensitive data)
ai-dev config show
# System information
uname -a
Enable Debug Mode
# Enable detailed logging
ai-dev review --verbose --debug
# Save logs to file
ai-dev review --verbose 2>&1 | tee ai-dev.log
Community Support
- Check existing issues:
- Join the community:
- Create a new issue:
- Include debug information
- Describe steps to reproduce
- Include relevant logs
Most issues can be resolved by checking configuration, updating dependencies, or using the correct command syntax. When in doubt, start with
ai-dev --help for command-specific guidance.