grokkit/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for Grokkit.

Table of Contents

• Installation Issues
• API & Network Issues
• Configuration Issues
• Git Integration Issues
• File Operation Issues
• Logging Issues
• Performance Issues

Installation Issues

Go version mismatch

Symptom:

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

Solution:

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

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

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

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

# ~/.config/grokkit/config.toml
timeout = 120  # Increase to 120 seconds

2. Check network connectivity:

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

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

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

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

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

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

# ~/.config/grokkit/config.toml
# Ensure aliases section is properly formatted

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

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

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

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

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

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

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

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

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

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

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

grokkit chat -m grok-4-mini

2. Reduce temperature (makes responses more deterministic/faster):

# ~/.config/grokkit/config.toml
temperature = 0.3

3. Check network latency:

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

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

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

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

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

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

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

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:

   grokkit <command> --debug
   

2. Check logs for specific errors:

   tail -100 ~/.config/grokkit/grokkit.log | jq 'select(.level=="ERROR")'
   

3. Verify environment:

   # 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 or Architecture docs.