Skip to content

Troubleshooting

Common issues and solutions.

Installation Issues

Knowledge Base Download Fails

Symptom: 

Error: Failed to download knowledge base
Connection timeout after 60s

Solution: 

# Retry with longer timeout
NOVA_KB_TIMEOUT=300 /init

# Or download manually
curl -L https://nova-ai.s3.amazonaws.com/kb-latest.tar.gz | \
  tar -xz -C ~/.nova-ai/knowledge-base/

MCP Server Won't Start

Symptom: 

Error: Failed to initialize sdk_mcp_kb_server
ModuleNotFoundError: No module named 'faiss'

Solution: 

# Install FAISS
pip install faiss-cpu

# Or for GPU support
pip install faiss-gpu

Runtime Issues

Agent Timeout

Symptom: 

Error: Agent timed out after 600s

Solutions:

  1. Increase timeout: 

    export NOVA_TIMEOUT=1200

  2. Break task into smaller pieces: 

    # Instead of
/novaai implement entire authentication system

# Do
/novaai implement user model
/novaai implement login endpoint
/novaai implement token refresh

Quality Gate Loops

Symptom: 

⚠️  Maximum retry attempts (3) reached
    Code-reviewer keeps finding issues

Solutions:

  1. Check the recurring issue: 

    # View last review
cat .nova-ai/logs/last-review.json

  2. Fix manually and retry: 

    # Apply suggested fix
vim src/problematic_file.py

# Retry
/novaai continue

Out of Memory

Symptom: 

Error: Killed (OOM)

Solutions:

  1. Reduce parallel agents: 

    export NOVA_MAX_PARALLEL=2

  2. Use smaller model for routine tasks: 

    # In .claude/agents/linter.md
model: claude-3-5-haiku-20241022

API Issues

Rate Limiting

Symptom: 

Error: 429 Too Many Requests
Rate limit exceeded

Solutions:

  1. Retry logic is handled automatically by the SDK with exponential backoff.

  2. Reduce parallel agents: 

    export NOVA_MAX_PARALLEL=2

Invalid API Key

Symptom: 

Error: 401 Unauthorized
Invalid API key

Solution: 

# Check key is set
echo $ANTHROPIC_API_KEY

# Verify key format (should start with sk-ant-)
export ANTHROPIC_API_KEY="sk-ant-..."

Git Issues

Worktree Conflicts

Symptom: 

Error: worktree already exists
fatal: '/tmp/nova-worktrees/abc123' already exists

Solution: 

# Clean up stale worktrees
git worktree prune

# Remove manually if needed
rm -rf /tmp/nova-worktrees/abc123

Uncommitted Changes Block Operation

Symptom: 

Error: Cannot proceed with uncommitted changes

Solutions:

  1. Commit or stash changes: 

    git stash
# or
git commit -m "WIP"

  2. Force continue (use with caution): 

    /novaai --force implement feature

Performance Issues

Symptom: 

KB search taking > 5s

Solutions:

  1. Rebuild index: 

    python scripts/rebuild_kb_index.py

  2. Reduce search scope: 

    from src.orchestrator.tools.kb_tools import search_knowledge_base

results = search_knowledge_base(
    query="authentication",
    top_k=3,  # Reduce from default 5
)

High Token Usage

Symptom: 

Warning: High token usage detected
Last task: 150,000 tokens

Solutions:

  1. Enable context compression: 

    export NOVA_COMPRESS_CONTEXT=true

  2. Break large tasks into smaller pieces to reduce context usage.

Debugging

Enable Verbose Logging

export NOVA_LOG_LEVEL=DEBUG
export NOVA_LOG_FILE=nova-debug.log

Trace Agent Communication

export NOVA_TRACE_AGENTS=true

View Last Error

cat ~/.nova-ai/logs/last-error.log

Check System Status

/background status

Getting Help

Log Collection

# Collect diagnostic info
python scripts/collect_diagnostics.py > diagnostics.txt

Report Issues

  1. Check existing issues: GitHub Issues
  2. Create new issue with:
  3. Nova AI version
  4. Python version
  5. Error message
  6. Steps to reproduce

What's Next?