grokkit/docs/TROUBLESHOOTING.md

# Troubleshooting Guide

Common issues and solutions for Grokkit.

## Table of Contents

- [Installation Issues](#installation-issues)
- [API & Network Issues](#api--network-issues)
- [Configuration Issues](#configuration-issues)
- [Git Integration Issues](#git-integration-issues)
- [File Operation Issues](#file-operation-issues)
- [Logging Issues](#logging-issues)
- [Performance Issues](#performance-issues)

## Installation Issues

### Go version mismatch

**Symptom:**
```
go: module gmgauthier.com/grokkit requires Go 1.24 or later
```

**Solution:**
```bash
# Check your Go version
go version

# Update Go to 1.24+
# Download from https://go.dev/dl/
```

### Make command not found

**Symptom:**
```
bash: make: command not found
```

**Solution:**
```bash
# macOS
brew install make

# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora
sudo dnf install make

# Or build manually
go build -o grokkit .
```

### Installation to ~/.local/bin fails

**Symptom:**
```
mkdir: cannot create directory '/home/user/.local/bin': Permission denied
```

**Solution:**
```bash
# Create the directory manually
mkdir -p ~/.local/bin

# Add to PATH if not already
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Then reinstall
make install
```

## API & Network Issues

### API key not set

**Symptom:**
```
Error: XAI_API_KEY environment variable not set
```

**Solution:**
```bash
# Set for current session
export XAI_API_KEY=sk-your-key-here

# Set permanently (bash)
echo 'export XAI_API_KEY=sk-your-key-here' >> ~/.bashrc
source ~/.bashrc

# Set permanently (zsh)
echo 'export XAI_API_KEY=sk-your-key-here' >> ~/.zshrc
source ~/.zshrc

# Verify
echo $XAI_API_KEY
```

### Request timeout

**Symptom:**
```
Error: Request failed: context deadline exceeded
```

**Solutions:**

**1. Increase timeout in config:**
```toml
# ~/.config/grokkit/config.toml
timeout = 120  # Increase to 120 seconds
```

**2. Check network connectivity:**
```bash
# Test xAI API access
curl -I https://api.x.ai/v1/models

# Check DNS resolution
nslookup api.x.ai

# Test with debug mode
grokkit chat --debug
```

**3. Check for proxy issues:**
```bash
# If behind corporate proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
```

### API rate limiting

**Symptom:**
```
Error: API error (status 429): Rate limit exceeded
```

**Solution:**
```bash
# Wait before retrying
sleep 60

# Use different model
grokkit chat -m grok-4-mini  # Faster, cheaper model

# Check your xAI dashboard for limits
```

### SSL/TLS certificate errors

**Symptom:**
```
Error: x509: certificate signed by unknown authority
```

**Solution:**
```bash
# Update CA certificates (Linux)
sudo update-ca-certificates

# Update CA certificates (macOS)
sudo security authorizationdb read com.apple.trust-settings > /tmp/trust.plist
sudo security authorizationdb write com.apple.trust-settings < /tmp/trust.plist

# Or check system time (certificate validation depends on time)
date
```

## Configuration Issues

### Config file not found

**Symptom:**
Config settings don't take effect.

**Solution:**
```bash
# Create config directory
mkdir -p ~/.config/grokkit

# Create config file
cat > ~/.config/grokkit/config.toml <<EOF
default_model = "grok-4"
temperature = 0.7
log_level = "info"
EOF

# Verify location
ls -la ~/.config/grokkit/config.toml
```

### Invalid TOML syntax

**Symptom:**
```
Error: failed to read config
```

**Solution:**
```bash
# Validate TOML syntax online: https://www.toml-lint.com/

# Or check with Go
go run -mod=mod github.com/pelletier/go-toml/v2/cmd/tomll@latest ~/.config/grokkit/config.toml

# Common errors:
# - Missing quotes around strings
# - Wrong indentation in sections
# - Duplicate keys
```

### Model alias not working

**Symptom:**
Using alias returns error or uses wrong model.

**Solution:**
```toml
# ~/.config/grokkit/config.toml
# Ensure aliases section is properly formatted

[aliases]
beta = "grok-beta-2"     # ✓ Correct
fast = "grok-4-mini"     # ✓ Correct
```

```bash
# Test alias
grokkit chat -m beta --debug  # Check which model is actually used
```

## Git Integration Issues

### Not in a git repository

**Symptom:**
```
Error: fatal: not a git repository
```

**Solution:**
```bash
# Initialize git repo if needed
git init

# Or cd into a git repository
cd /path/to/your/repo

# Verify
git status
```

### No staged changes

**Symptom:**
```
No staged changes!
```

**Solution:**
```bash
# Stage your changes first
git add <files>

# Or stage all changes
git add .

# Verify
git status

# Then run grokkit
grokkit commit
```

### Git command not found

**Symptom:**
```
Error: git command failed: exec: "git": executable file not found
```

**Solution:**
```bash
# Install git
# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Fedora
sudo dnf install git

# Verify
git --version
```

## File Operation Issues

### File not found

**Symptom:**
```
File not found: main.go
```

**Solution:**
```bash
# Check file exists
ls -la main.go

# Use absolute or relative path
grokkit edit ./main.go "instruction"
grokkit edit /full/path/to/main.go "instruction"

# Check current directory
pwd
ls
```

### Permission denied on backup creation

**Symptom:**
```
Failed to create backup: permission denied
```

**Solution:**
```bash
# Check file permissions
ls -la main.go

# Check directory permissions
ls -ld .

# Fix permissions
chmod 644 main.go    # File
chmod 755 .          # Directory

# Or run from writable directory
```

### Failed to write file

**Symptom:**
```
Failed to write file: permission denied
```

**Solution:**
```bash
# Check if file is read-only
ls -la main.go

# Make writable
chmod 644 main.go

# Check disk space
df -h .

# Check if file is open in another program
lsof | grep main.go
```

## Logging Issues

### Log file permission denied

**Symptom:**
```
Error: failed to open log file: permission denied
```

**Solution:**
```bash
# Fix log directory permissions
chmod 755 ~/.config/grokkit
chmod 644 ~/.config/grokkit/grokkit.log

# Or recreate log directory
rm -rf ~/.config/grokkit
mkdir -p ~/.config/grokkit
```

### Log file too large

**Symptom:**
Log file consuming excessive disk space.

**Solution:**
```bash
# Check log size
du -h ~/.config/grokkit/grokkit.log

# Truncate log file
: > ~/.config/grokkit/grokkit.log

# Or rotate logs manually
mv ~/.config/grokkit/grokkit.log ~/.config/grokkit/grokkit.log.old
gzip ~/.config/grokkit/grokkit.log.old

# Set up log rotation (Linux)
sudo tee /etc/logrotate.d/grokkit <<EOF
/home/*/.config/grokkit/grokkit.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}
EOF
```

### Debug output not showing

**Symptom:**
`--debug` flag doesn't show output.

**Solution:**
```bash
# Ensure you're using the flag correctly
grokkit chat --debug  # ✓ Correct
grokkit --debug chat  # ✗ Wrong order

# Check log level in config
cat ~/.config/grokkit/config.toml | grep log_level

# Force debug via config
echo 'log_level = "debug"' >> ~/.config/grokkit/config.toml

# Or set via environment
export LOG_LEVEL=debug
```

## Performance Issues

### Slow API responses

**Symptom:**
Requests take very long to complete.

**Solutions:**

**1. Use faster model:**
```bash
grokkit chat -m grok-4-mini
```

**2. Reduce temperature (makes responses more deterministic/faster):**
```toml
# ~/.config/grokkit/config.toml
temperature = 0.3
```

**3. Check network latency:**
```bash
# Test API latency
time curl -s https://api.x.ai/v1/models > /dev/null

# Check DNS resolution time
time nslookup api.x.ai
```

**4. Review logs for timing:**
```bash
# Check actual API duration
cat ~/.config/grokkit/grokkit.log | \
  jq 'select(.msg=="API request completed") | {model, duration_ms}'
```

### High memory usage

**Symptom:**
Grokkit consuming excessive memory.

**Solution:**
```bash
# Check memory usage
top -p $(pgrep grokkit)

# Clear chat history if very large
rm ~/.config/grokkit/chat_history.json

# Limit history size (future feature)
# For now, manually trim history file
```

### Chat history growing too large

**Symptom:**
Chat becomes slow or fails to save.

**Solution:**
```bash
# Check history size
du -h ~/.config/grokkit/chat_history.json

# Back up and clear
mv ~/.config/grokkit/chat_history.json \
   ~/.config/grokkit/chat_history.backup.json

# Or manually trim to last N exchanges
cat ~/.config/grokkit/chat_history.json | \
  jq '.messages[-20:]' > ~/.config/grokkit/chat_history.new.json
mv ~/.config/grokkit/chat_history.new.json \
   ~/.config/grokkit/chat_history.json
```

## 7. Linter Issues

### No linter found for language

**Symptom:**
```
⚠️  no linter found for Go

Install one of:
  - golangci-lint: https://golangci-lint.run/usage/install/
  - go vet: Built-in with Go
```

**Solution:**
```bash
# Install appropriate linter for your language

# Go
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
# Or use go vet (built-in)

# Python
pip install pylint flake8 ruff

# JavaScript/TypeScript
npm install -g eslint

# Rust
rustup component add clippy

# Ruby
gem install rubocop

# Shell
# Ubuntu/Debian
apt install shellcheck
# macOS
brew install shellcheck

# Verify installation
which golangci-lint  # or your linter command
```

### Linter found issues but AI fixes failed

**Symptom:**
Linter reports issues but AI returns empty response or invalid code.

**Solution:**
```bash
# 1. Try with a different model
grokkit lint file.py -m grok-4

# 2. Check the linter output is clear
grokkit lint file.py --dry-run

# 3. Try manual fix first, then use edit command
grokkit edit file.py "fix the issues reported by linter"

# 4. Enable debug logging to see API interaction
grokkit lint file.py --debug
```

### Linter verification still shows issues

**Symptom:**
After applying AI fixes, re-running the linter still reports issues.

**Solution:**
```bash
# Some issues may require manual intervention
# Use git diff to compare changes
git diff file.py

# Apply fixes iteratively
grokkit lint file.py         # Apply fixes
grokkit lint file.py         # Run again on remaining issues

# For complex issues, use edit with specific instructions
grokkit edit file.py "fix the remaining pylint warnings about docstrings"
```

### File extension not recognized

**Symptom:**
```
unsupported file type: .xyz
```

**Solution:**
Currently supported extensions:
- **Go:** `.go`
- **Python:** `.py`
- **JavaScript:** `.js`, `.jsx`
- **TypeScript:** `.ts`, `.tsx`
- **Rust:** `.rs`
- **Ruby:** `.rb`
- **Java:** `.java`
- **C/C++:** `.c`, `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp`
- **Shell:** `.sh`, `.bash`

For unsupported languages, use the `edit` command instead:
```bash
grokkit edit myfile.xyz "review and fix code quality issues"
```

### Wrong linter used

**Symptom:**
Tool uses go vet but you want golangci-lint, or uses flake8 but you want ruff.

**Explanation:**
Grokkit tries linters in the order defined and uses the first available one. To use a specific linter, ensure it's installed and others are not in PATH, or contribute to the project to add linter preference configuration.

**Current linter priority:**
- **Go:** golangci-lint → go vet
- **Python:** pylint → flake8 → ruff
- **JavaScript:** eslint
- **TypeScript:** eslint → tsc

## Getting Help

If none of these solutions work:

1. **Enable debug mode** to see detailed logging:
   ```bash
   grokkit <command> --debug
   ```

2. **Check logs** for specific errors:
   ```bash
   tail -100 ~/.config/grokkit/grokkit.log | jq 'select(.level=="ERROR")'
   ```

3. **Verify environment**:
   ```bash
   # Check versions
   go version
   git --version

   # Check config
   cat ~/.config/grokkit/config.toml

   # Check API key is set
   echo $XAI_API_KEY | sed 's/sk-.*$/sk-***/'
   ```

4. **Report issue** with:
   - Error message
   - Command used
   - Relevant logs (sanitize API keys!)
   - OS and Go version

---

**Still having issues?** Check the [Configuration Guide](CONFIGURATION.md) or [Architecture](ARCHITECTURE.md) docs.