Troubleshooting

This guide addresses common issues you might encounter while using noidea.

Installation Issues

noidea Command Not Found

Problem: After installation, running noidea results in "command not found".

Solutions:

1. Check if the binary is in your PATH:

   which noidea
   

2. If not found, verify the installation location:

   # Installed to /usr/local/bin
   ls -la /usr/local/bin/noidea
   
   # Or in your Go bin directory
   ls -la ~/go/bin/noidea
   

3. Add the installation directory to your PATH if needed:

   # Add to your .bashrc or .zshrc
   export PATH=$PATH:/path/to/directory
   

Installation Fails with Permission Error

Problem: ./install.sh fails with permission errors.

Solution: Run with sudo or specify a user-writable location:

sudo ./install.sh
# Or
./install.sh --prefix ~/bin

API Key Issues

API Key Validation Fails

Problem: "API key validation error" or "Invalid API key" messages.

Solutions:

1. Verify your API key:

   noidea config apikey-status
   

2. Re-enter your API key:

   noidea config apikey
   

3. Check your internet connection and provider status.

Can't Access AI Features

Problem: AI-powered features like suggest --ai or moai --ai don't work.

Solutions:

1. Ensure AI features are enabled:

   # Check configuration
   noidea config --show | grep enabled
   
   # Enable if needed
   noidea config set llm.enabled true
   

2. Set up your API key if you haven't already:

   noidea config apikey
   

Git Integration Issues

Git Hooks Not Working

Problem: noidea's Git hooks (commit suggestions, Moai feedback) aren't running.

Solutions:

1. Verify hooks are installed in your repository:

   ls -la .git/hooks/prepare-commit-msg .git/hooks/post-commit
   

2. If missing, run:

   noidea init
   

3. Ensure hooks are executable:

   chmod +x .git/hooks/prepare-commit-msg .git/hooks/post-commit
   

4. Check if hooks are bypassed:

   # Make sure you're not using --no-verify
   git config --get noidea.suggest
   

Commit Suggestions Not Appearing

Problem: The commit message suggestion feature isn't working.

Solutions:

1. Make sure it's enabled:

   git config --get noidea.suggest
   
   # Enable if needed
   git config noidea.suggest true
   

2. Verify you have staged changes:

   git status
   

3. Try running the suggest command directly:

   noidea suggest
   

Performance Issues

Slow Commit Suggestions

Problem: Generating commit suggestions takes too long.

Solutions:

1. Disable full-diff mode:

   git config noidea.suggest.full-diff false
   

2. Reduce history context:

   git config noidea.suggest.history 5
   

Configuration Issues

Configuration Changes Not Applied

Problem: Changes to configuration don't seem to take effect.

Solutions:

1. Check current configuration:

   noidea config --show
   

2. Verify configuration file location:

   ls -la ~/.noidea/config.json
   

3. Ensure you're using the correct method (environment variables might override file settings).

Getting More Help

If your issue isn't addressed here:

1. Check the logs for more information (if enabled):

   cat ~/.noidea/logs/noidea.log
   

2. Open an issue on GitHub with:

3. noidea version (noidea --version)
4. OS details
5. Error messages
6. Steps to reproduce