troubleshooting

Troubleshooting Guide

This guide helps you diagnose and fix common issues with Harper.

Common Issues

1. Installation Problems

Error: Command not found: harper

harper: command not found

Solution:

1. Ensure you've installed Harper:

   cargo install --path .

2. Add Cargo's bin directory to your PATH:

   echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc

2. API Connection Issues

Error: Failed to connect to API

Error: Failed to connect to API: Connection refused

Solution:

1. Check your internet connection
2. Verify your API key is correct
3. Check if the API service is down
4. If using a proxy, configure it:

   export https_proxy=http://your-proxy:port

3. Authentication Failures

Error: Invalid API Key

Error: 401 Unauthorized - Invalid API key

Solution:

1. Verify your API key in ~/.config/harper/config.toml
2. Ensure there are no extra spaces or special characters
3. Regenerate your API key if needed
4. Check your account's usage limits

Performance Issues

1. Slow Response Times

Possible Causes:

• Network latency
• High server load
• Large context size

Mitigation:

[model]
max_tokens = 512  # Reduce max tokens
temperature = 0.3  # Lower for more focused responses

2. High Memory Usage

Symptoms:

• Application becomes unresponsive
• System slows down

Solution:

1. Limit context size:

   [context]
   max_history = 10  # Keep last 10 messages
   max_tokens = 4096  # Limit context tokens

2. Close unused sessions
3. Clear conversation history:

   /clear_history
   

Error Messages

1. Rate Limit Exceeded

Error: Rate limit exceeded. Please try again in 20s

Solution:

1. Wait before making more requests
2. Upgrade your API plan if needed
3. Implement exponential backoff

2. Model Not Available

Error: Model 'gpt-5' does not exist

Solution:

1. Check the model name spelling
2. Verify the model is available in your region
3. Update to the latest version of Harper

Debugging

Enable Debug Logs

# Set log level
export RUST_LOG=debug
harper

Check Logs

Logs are stored in:

• Linux/Mac: ~/.local/share/harper/logs/
• Windows: %APPDATA%\harper\logs\

Common Fixes

Reset Configuration

rm ~/.config/harper/config.toml
harper setup

Clear Cache

rm -rf ~/.cache/harper

Update Harper

cd /path/to/harper
git pull
cargo install --path . --force

Getting Help

Check Documentation

/help
/help commands
/help config

Report Issues

If you can't resolve your issue:

1. Check GitHub Issues
2. Include:
   • Harper version (harper --version)
   • OS and version
   • Steps to reproduce
   • Error logs
   • Configuration (with sensitive info removed)