CodeWave Troubleshooting Guide

November 8, 2025 ยท View on GitHub

Comprehensive troubleshooting for common issues and how to resolve them.

Table of Contents

  1. Installation Issues
  2. Configuration Issues
  3. API & Authentication
  4. Evaluation Issues
  5. Performance Issues
  6. Output Issues
  7. Advanced Debugging

Installation Issues

Problem: Command Not Found

command not found: codewave

Cause

CodeWave is not installed or not in PATH.

Solution

Option 1: Install Globally

npm install -g codewave

Option 2: Install Locally

npm install codewave
# Run with npx
npx codewave evaluate HEAD

Option 3: Check Installation

# Check if installed
which codewave
npm list -g codewave

# Reinstall if needed
npm uninstall -g codewave
npm install -g codewave

# Verify
codewave --version

Problem: Permission Denied

Error: EACCES: permission denied

Cause

Insufficient permissions for npm global installation.

Solution

Option 1: Fix npm Permissions

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Option 2: Use sudo (Not Recommended)

sudo npm install -g codewave

Problem: Old Version Installed

codewave --version
# Output: 0.9.0 (outdated)

Solution

# Update to latest
npm install -g codewave@latest

# Or reinstall
npm uninstall -g codewave
npm install -g codewave

# Verify
codewave --version

Configuration Issues

Problem: Configuration File Not Found

Error: Configuration file not found
Please run: codewave config

Cause

First-time setup not completed.

Solution

# Run interactive configuration
codewave config

# Or set via environment variables
export CODEWAVE_LLM_PROVIDER=anthropic
export CODEWAVE_API_KEY=sk-ant-...
export CODEWAVE_MODEL=claude-3-5-sonnet-20241022

# Verify
codewave config show

Problem: Invalid Configuration

Error: Invalid configuration format

Cause

Configuration file is corrupted or invalid JSON.

Solution

Option 1: Backup and Reset

# Backup current config
cp ~/.codewave/config.json ~/.codewave/config.json.backup

# Reset to defaults
codewave config reset

# Reconfigure
codewave config

Option 2: Manual Fix

# Edit configuration file directly
cat ~/.codewave/config.json  # View contents
nano ~/.codewave/config.json # Edit

# Validate JSON online or with jq
jq . ~/.codewave/config.json

Problem: Configuration Not Being Applied

Expected: model X
Actual: model Y

Cause

Environment variables or CLI arguments overriding configuration file.

Resolution Order (highest priority first):

  1. CLI arguments (--model, --format)
  2. Environment variables (CODEWAVE_MODEL)
  3. Configuration file (~/.codewave/config.json)
  4. Defaults

Solution

# Check current config
codewave config show

# Check environment variables
env | grep CODEWAVE

# Remove conflicting variables
unset CODEWAVE_MODEL

# Set via config
codewave config set model claude-3-5-sonnet-20241022

API & Authentication

Problem: "API Key Not Found"

Error: API key not found
Please configure with: codewave config set api-key <key>

Solution

Option 1: Set via Config

codewave config set api-key sk-ant-...
codewave config show  # Verify

Option 2: Set via Environment Variable

export CODEWAVE_API_KEY=sk-ant-...
codewave evaluate HEAD

Option 3: Interactive Config

codewave config  # Will prompt for API key

Problem: "Invalid API Key"

Error: 401 Unauthorized - Invalid API key

Cause

API key is incorrect, expired, or revoked.

Solution

Step 1: Verify Key Format

# Key should start with provider prefix
# Anthropic: sk-ant-...
# OpenAI: sk-...
# Google: AIza... or api-key-...

codewave config show | grep api-key

Step 2: Check Key Validity

  • Visit provider's API key management page
  • Verify key hasn't been revoked
  • Check expiration date if applicable

Step 3: Regenerate and Update

# 1. Generate new key from provider
# 2. Update CodeWave
codewave config set api-key <new-key>

# 3. Verify
codewave evaluate HEAD --verbose

Problem: "Provider Not Found"

Error: LLM provider 'anthropic' not found

Cause

Invalid provider name or provider not installed.

Solution

# Check current configuration
codewave config show

# Set to valid provider
codewave config set llm-provider anthropic  # Anthropic
codewave config set llm-provider openai     # OpenAI
codewave config set llm-provider google     # Google Gemini

Problem: "Model Not Available"

Error: Model 'claude-99' is not available

Cause

Model doesn't exist for selected provider.

Solution

# Anthropic models
codewave config set model claude-3-5-sonnet-20241022
codewave config set model claude-3-opus-20250219
codewave config set model claude-3-haiku-20240307

# OpenAI models
codewave config set model gpt-4o
codewave config set model gpt-4-turbo
codewave config set model gpt-4

# Google models
codewave config set model gemini-2.0-flash
codewave config set model gemini-1.5-pro

Evaluation Issues

Problem: "Commit Not Found"

Error: Commit 'abc1234' not found in repository

Cause

Invalid commit hash or reference.

Solution

# Verify you're in a Git repository
pwd
git status

# List available commits
git log --oneline -10

# Use valid reference
codewave evaluate HEAD           # Latest
codewave evaluate HEAD~1         # Previous
codewave evaluate abc1234        # Specific hash
codewave evaluate develop        # Branch name

Problem: "Repository Not Found"

Error: Not a git repository
fatal: not a git repository (or any of the parent directories)

Cause

Not in a Git repository directory.

Solution

# Check if in Git repo
ls -la | grep ".git"

# Navigate to repository root
cd ~/my-project

# Or specify repository path
codewave evaluate HEAD --repo /path/to/repo

Problem: "No Commits to Evaluate"

Error: No commits found in range

Cause

Commit range is empty or invalid date filters.

Solution

# Check available commits
git log --oneline --since="2024-01-01" --until="2024-01-31"

# Adjust date range
codewave batch-evaluate --since "2024-01-01" --until "2024-02-01"

# Or use count instead
codewave batch-evaluate --count 10

Problem: "Evaluation Timeout"

Error: Evaluation timed out after 120 seconds

Cause

Large diff or slow LLM API.

Solution

For Large Diffs:

# Enable RAG for automatic chunking
codewave config set enable-rag true
codewave config set rag-chunk-size 2000

# Re-evaluate
codewave evaluate HEAD --verbose

For Slow API:

# Use faster model
codewave config set model claude-3-haiku-20240307

# Or different provider
codewave config set llm-provider google
codewave config set model gemini-2.0-flash

# Increase timeout if available
codewave evaluate HEAD --timeout 300

Problem: "Diff Too Large"

Error: Diff exceeds maximum size (100KB)
Warning: Consider enabling RAG

Cause

Commit diff is too large for efficient processing.

Solution

Option 1: Enable RAG

codewave config set enable-rag true
codewave config set rag-chunk-size 2000
codewave evaluate HEAD

Option 2: Increase Threshold

# Set threshold to 200KB
codewave config set rag-threshold 204800

Option 3: Process Smaller Commits

# Evaluate individual files instead
git diff HEAD~1 -- src/auth.ts | codewave evaluate --stdin

Performance Issues

Problem: Slow Evaluations

Evaluation takes 10+ seconds per commit.

Cause

Using high-quality but slow model, or network latency.

Solution

Option 1: Use Faster Model

codewave config set model claude-3-haiku-20240307
codewave evaluate HEAD --verbose

Option 2: Reduce Token Limit

codewave config set max-tokens 2000
codewave evaluate HEAD --verbose

Option 3: Skip Report Generation

codewave evaluate HEAD --no-report --format json

Problem: High Memory Usage

Error: JavaScript heap out of memory

Cause

Processing too many commits in parallel or very large diffs.

Solution

Option 1: Reduce Parallelization

codewave config set parallel-evaluations 1
codewave batch-evaluate --count 100

Option 2: Process Smaller Batches

codewave batch-evaluate --count 10  # Instead of 100

# Then process next batch
codewave batch-evaluate --count 10 --since "2024-01-15"

Option 3: Enable Vector Store Optimization

# Use disk-based vector store for large commits
codewave config set vector-store-type disk

Problem: High Cost

Costs are unexpectedly high.

Solution

Option 1: Use Cheaper Model

# Google Gemini (10x cheaper)
codewave config set llm-provider google
codewave config set model gemini-2.0-flash

# Or Anthropic Haiku
codewave config set model claude-3-haiku-20240307

Option 2: Reduce Token Usage

# Smaller token limit
codewave config set max-tokens 2000

# Smaller RAG chunks
codewave config set rag-chunk-size 1000

Option 3: Batch Efficiently

# Process in parallel to reduce overhead
codewave batch-evaluate --count 100 --parallel 5

Output Issues

Problem: "Output Directory Permission Denied"

Error: EACCES: permission denied, open '.evaluated-commits'

Cause

No write permission to output directory.

Solution

# Check permissions
ls -la .evaluated-commits

# Fix permissions
chmod 755 .evaluated-commits

# Or use different directory
codewave evaluate HEAD -o ~/codewave-results

# Or check disk space
df -h

Problem: "HTML Report Not Opening"

Report saved, but can't open report.html

Solution

# Find the report
find .evaluated-commits -name "report.html" | head -1

# Open manually
open .evaluated-commits/*/report.html

# Or in specific browser
google-chrome .evaluated-commits/*/report.html

# Or serve with HTTP server
python3 -m http.server 8000
# Then visit http://localhost:8000/.evaluated-commits/*/report.html

Problem: "JSON Results Invalid"

Error: JSON parse error

Solution

# Validate JSON
jq . .evaluated-commits/*/results.json

# Check for corruption
file .evaluated-commits/*/results.json

# Re-evaluate if corrupted
rm .evaluated-commits/*/results.json
codewave evaluate HEAD --format json

Advanced Debugging

Enable Verbose Logging

# Run with verbose output
codewave evaluate HEAD --verbose

# Enable for all operations
codewave config set verbose true
codewave evaluate HEAD

Verbose Output Shows:

  • Agent prompts and responses
  • Token counts and costs
  • Timing for each stage
  • Full LLM API interactions
  • Error stack traces

Check System Information

# Node.js version
node --version

# npm version
npm --version

# CodeWave version
codewave --version

# Git version
git --version

# OS information
uname -a

# Disk space
df -h

# Memory usage
free -h  # Linux
vm_stat  # macOS

Verify Network Connectivity

# Test API connectivity
curl -I https://api.anthropic.com

# Test DNS
nslookup api.anthropic.com

# Check proxy settings
env | grep -i proxy

Enable Core Dumps (Advanced)

# Linux: Enable core dumps for crash analysis
ulimit -c unlimited

# macOS: Similar approach
defaults write com.apple.CrashReporter CrashReportingEnabled 1

Collect Debug Information

#!/bin/bash

echo "=== System Information ===" > debug-info.txt
uname -a >> debug-info.txt
node --version >> debug-info.txt
npm --version >> debug-info.txt
codewave --version >> debug-info.txt

echo "=== CodeWave Configuration ===" >> debug-info.txt
codewave config show >> debug-info.txt

echo "=== Environment Variables ===" >> debug-info.txt
env | grep -i codewave >> debug-info.txt

echo "=== Git Information ===" >> debug-info.txt
git log --oneline -5 >> debug-info.txt

echo "Debug info collected in: debug-info.txt"

Enable Stack Traces

# Run with Node.js debugging
node --inspect-brk `which codewave` evaluate HEAD

# Or with more verbose Node output
NODE_DEBUG=* codewave evaluate HEAD 2>&1 | head -100

Getting Help

Before Asking for Help

  1. Check This Guide: Search for your error message above
  2. Enable Verbose: Run with --verbose flag for more info
  3. Check Version: Ensure you're running latest version
  4. Collect Info: Run the debug information script above
  5. Try Different Model: Test with different LLM provider
  6. Check Documentation: See README.md

Where to Get Help

GitHub Issues:

https://github.com/techdebtgpt/codewave/issues

Email Support:

support@techdebtgpt.com

Discussions:

https://github.com/techdebtgpt/codewave/discussions

Reporting Issues

When reporting, include:

  1. Error Message: Exact error text
  2. Reproduction Steps: How to reproduce
  3. System Info: OS, Node version, CodeWave version
  4. Configuration: Your config (mask API keys)
  5. Logs: Output from --verbose flag
  6. Expected Behavior: What should happen
  7. Actual Behavior: What actually happens

Example issue:

## Bug: Evaluation Timeout on Large Commits

### Error Message

Error: Evaluation timed out after 120 seconds


### Reproduction
1. Create commit with 150KB diff
2. Run: `codewave evaluate HEAD`
3. Wait 120 seconds...

### Environment
- OS: macOS 14.1
- Node: 18.18.0
- CodeWave: 1.0.0
- Model: claude-3-5-sonnet-20241022

### Configuration
```json
{
  "llmProvider": "anthropic",
  "model": "claude-3-5-sonnet-20241022",
  "enableRag": false
}

Expected

Should complete evaluation in 5-10 seconds

Actual

Times out after 120 seconds

Solution Attempted

  • Tried different model (same issue)
  • Tried smaller commits (works fine)

### Problem: LLM JSON Parsing Errors

Failed to parse LLM output: Unexpected non-whitespace character after JSON Unexpected token '#'


#### Cause
Any model (Haiku, Sonnet, GPT, Gemini, Grok) can generate responses that are truncated or include extra content after JSON when approaching token limits.

#### Solution

**Option 1: Already Fixed (v0.0.1+)**
Automatic JSON recovery is built in for all models:
- Extracts JSON even if extra markdown content follows
- Auto-closes incomplete JSON structures
- Provides detailed error logging for debugging

The system gracefully handles truncated responses by:
1. Extracting the JSON object using regex
2. Closing incomplete braces
3. Falling back to text summary if JSON parsing completely fails

No action needed - evaluation continues with best-effort parsing.

**Option 2: Default Configuration (Recommended)**
- **maxTokens**: Now set to 16000 for all models
  - Increased from 8000 to prevent truncation
  - Applies to all LLM providers (Anthropic, OpenAI, Google, xAI)
  - Should eliminate most JSON parsing errors

**Option 3: Use Better Model (if issues persist)**
```bash
# Try a more capable model with better JSON output
codewave config set model claude-sonnet-4-5-20250929  # Sonnet (~4x cost)
codewave config set model gpt-4o                       # OpenAI GPT-4o
codewave config set model gemini-2.5-pro               # Google Gemini

Option 4: Manually Increase maxTokens Further

# View current settings
codewave config show

# If issues still persist, increase maxTokens further
# (This may increase API costs depending on provider)

Why This Happens with Any Model

  • Models can generate verbose responses that approach token limits
  • Default maxTokens increased to 16000 to prevent truncation across all providers
  • JSON recovery system handles any remaining edge cases
  • Multi-agent discussion provides additional refinement opportunities

Quick Fix Checklist

  • Reinstall CodeWave: npm install -g codewave
  • Check version: codewave --version
  • Reset config: codewave config reset
  • Reconfigure: codewave config
  • Verify API key: codewave config show
  • Try verbose: codewave evaluate HEAD --verbose
  • Check permissions: ls -la ~/.codewave
  • Check disk space: df -h
  • Verify Git repo: git status
  • Try different model: codewave config set model claude-sonnet-4-5-20250929

For more information: