Troubleshooting

Common issues and solutions

Common Issues

Out of Memory Errors

Symptom

JavaScript heap out of memory
Allocation failed - process out of memory

Cause

Large repositories (10,000+ files) may exceed the default Node.js heap limit.

Solution

GitNexus automatically allocates 8GB heap on first run. If you still hit OOM:

Option 1: Manual heap increase

NODE_OPTIONS="--max-old-space-size=16384" gitnexus analyze

Option 2: Skip embeddings

Embeddings require significant memory. Analyze without them:

gitnexus analyze  # Default: no embeddings

Option 3: Increase system swap

On Linux/macOS, increase swap space for very large repos.

Prevention

• Exclude large directories: Add to .gitignore before indexing
• Skip generated files: Ensure dist/, build/, node_modules/ are ignored
• Use embedding limit: Embeddings auto-skip for repos >50,000 nodes

---

Stale Index Warning

Symptom

⚠️  Index is stale (last indexed: 3 days ago, current commit: abc123)

Cause

Your repository has new commits since the last index. The knowledge graph may be out of sync with your code.

Solution

Option 1: Re-analyze (incremental)

gitnexus analyze

This auto-detects changes and re-indexes only if the commit hash changed.

Option 2: Force full re-index

gitnexus analyze --force

Ignores staleness check and rebuilds from scratch.

Check Index Status

gitnexus status

Shows:

• Last indexed commit
• Current commit
• Number of nodes/edges
• Index freshness

---

Parser Errors

Symptom

Error parsing file: src/utils/helper.ts
Tree-sitter parse failed

Cause

Tree-sitter may fail on:

• Minified code (e.g., bundle.min.js)
• Extremely large files (>10MB single file)
• Syntax errors (incomplete or invalid code)
• Unsupported language (file extension not recognized)

Solution

Option 1: Exclude problematic files

Add to .gitignore:

# Exclude minified files
*.min.js
*.min.css

# Exclude large generated files
dist/bundle.js

Option 2: Fix syntax errors

If the file has syntax errors, fix them first:

tsc --noEmit  # For TypeScript
pylint src/  # For Python

Option 3: Skip specific files

GitNexus respects .gitignore. Add files you want to skip:

echo "src/problematic/file.ts" >> .gitignore
gitnexus analyze

---

KuzuDB Errors

Symptom

KuzuDB initialization failed
Database file corrupted

Cause

• Corrupted database (power loss, disk error)
• Permission issues (can’t write to .gitnexus/)
• Disk full (no space for database)

Solution

Option 1: Delete and re-index

gitnexus clean
gitnexus analyze

Option 2: Check disk space

df -h  # Linux/macOS

Ensure you have at least 2x your repo size in free space.

Option 3: Check permissions

ls -la .gitnexus/

Ensure you own the directory:

sudo chown -R $(whoami) .gitnexus/

---

Embedding Model Download Fails

Symptom

Failed to download snowflake-arctic-embed-xs
Network timeout

Cause

• No internet connection
• Firewall blocking Hugging Face
• Disk full (model is ~90MB)

Solution

Option 1: Skip embeddings

gitnexus analyze  # Default: no embeddings

You can still use all other features (search, context, impact).

Option 2: Retry with embeddings

gitnexus analyze --embeddings

Option 3: Use VPN/proxy

If Hugging Face is blocked:

export HTTPS_PROXY=http://your-proxy:8080
gitnexus analyze --embeddings

Option 4: Manual model download

Download model manually and place in cache:

mkdir -p ~/.cache/huggingface/hub/
# Download from https://huggingface.co/Snowflake/snowflake-arctic-embed-xs

---

MCP Server Not Responding

Symptom

• Cursor/Claude shows “MCP server error”
• Tools not available
• “gitnexus not found”

Cause

• Not installed globally (using npx is recommended)
• Wrong config path
• Server crashed

Solution

Option 1: Restart editor

Close and reopen Cursor/Claude/Windsurf.

Option 2: Check MCP config

Verify config file exists:

# Cursor
cat ~/.cursor/mcp.json

# Claude Code
claude mcp list

# OpenCode
cat ~/.config/opencode/config.json

Should contain:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Option 3: Run MCP server manually

Test if the server starts:

npx gitnexus mcp

Should output JSON-RPC messages. If it crashes, check the error.

Option 4: Re-run setup

gitnexus setup

This auto-detects editors and writes the correct config.

---

”Repository not indexed” Error

Symptom

Error: Repository not indexed
No .gitnexus directory found

Cause

You’re trying to query a repo that hasn’t been indexed yet.

Solution

Option 1: Index the repo

cd /path/to/your/repo
gitnexus analyze

Option 2: Check you’re in the right directory

pwd  # Should be inside your git repo
git status  # Should show git info

Option 3: Check global registry

cat ~/.gitnexus/registry.json

If the repo is missing, run gitnexus analyze again.

---

Slow Indexing Performance

Symptom

Indexing takes >10 minutes for a medium-sized repo (~1,000 files).

Cause

• Slow disk (HDD vs SSD)
• Many large files (e.g., 1MB+ source files)
• CPU-bound (single-core or old CPU)
• Embeddings enabled (adds significant time)

Solution

Option 1: Disable embeddings

gitnexus analyze  # 2-5x faster without embeddings

Option 2: Exclude large directories

Add to .gitignore:

vendor/
third_party/
*.generated.ts

Option 3: Use SSD

Move repo to SSD for faster I/O.

Option 4: Check CPU usage

top  # Should see 100% CPU (multi-core)

If CPU is low, worker threads may not be starting. Check for errors.

---

Swift Parser Installation Fails

Symptom

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: tree-sitter-swift

Cause

tree-sitter-swift is an optional dependency that may fail on some platforms.

Solution

Option 1: Ignore it

This is a warning, not an error. GitNexus will work for all other languages.

Option 2: Install without optional dependencies

npm install --no-optional gitnexus

Option 3: Build Swift parser manually

If you need Swift support:

npm install tree-sitter-swift --build-from-source

---

Performance Tips

For Large Repositories

1. Skip embeddings - Use default (no --embeddings flag)
2. Exclude generated code - Add dist/, build/ to .gitignore
3. Use SSD - Significantly faster than HDD
4. Increase heap - Use NODE_OPTIONS="--max-old-space-size=16384"
5. Run overnight - Very large repos (50,000+ files) may take hours

For Faster Queries

1. Use specific queries - Narrow searches are faster than broad ones
2. Leverage processes - Results grouped by execution flow
3. Use context tool - More efficient than raw Cypher for symbol lookups
4. Cache embeddings - Re-index without --force to reuse embeddings

For Web UI

1. Use local backend - Run gitnexus serve for already-indexed repos
2. Limit file selection - Don’t upload entire repos (use CLI instead)
3. Use Chrome/Edge - WebGPU support for faster embeddings

---

Diagnostic Commands

Check Index Status

gitnexus status

Shows:

• Index freshness
• Node/edge counts
• Last indexed commit
• Embedding status

List All Indexed Repos

gitnexus list

Shows all repos in global registry.

Verify KuzuDB

du -sh .gitnexus/graph.kuzu

Database size should be ~1-10MB per 1,000 files.

Test MCP Connection

npx gitnexus mcp

Should output JSON-RPC init messages.

---

Clean Up and Reset

Delete Index for Current Repo

gitnexus clean

Removes .gitnexus/ directory and unregisters from global registry.

Delete All Indexes

gitnexus clean --all --force

Removes:

• ~/.gitnexus/registry.json
• All per-repo .gitnexus/ directories (requires confirmation)

Re-index from Scratch

gitnexus clean
gitnexus analyze --force --embeddings

Clear Embedding Model Cache

# Linux/macOS
rm -rf ~/.cache/huggingface/hub/models--Snowflake--snowflake-arctic-embed-xs

# Windows
rmdir /s "%LOCALAPPDATA%\huggingface\hub\models--Snowflake--snowflake-arctic-embed-xs"

---

Debug Mode

Enable Verbose Logging

NODE_ENV=development gitnexus analyze

Shows:

• Detailed pipeline progress
• Parser stats
• Memory usage
• Worker thread activity

Inspect Database

Use KuzuDB CLI to inspect the graph:

npx kuzu .gitnexus/graph.kuzu

Run Cypher queries:

MATCH (f:Function) RETURN f.name LIMIT 10;

---

Getting Help

GitHub Issues

Report bugs or request features:

github.com/abhigyanpatwari/GitNexus/issues

Discussions

Ask questions or share tips:

github.com/abhigyanpatwari/GitNexus/discussions

Discord

Join the community:

Discord link in repo

---

Error Reference

Exit Codes

• 0 - Success
• 1 - General error (parse failure, disk error, etc.)
• 130 - Interrupted (Ctrl+C)

Common Error Messages

Error	Cause	Solution
Not a git repository	Not inside a git repo	Run git init or cd to a git repo
KuzuDB not initialized	Database connection failed	Run gitnexus clean then re-analyze
Embedder not initialized	Model failed to load	Skip embeddings or check internet
Worker thread timeout	Parsing stuck on a file	Exclude the problematic file
ENOSPC: no space left	Disk full	Free up disk space
EACCES: permission denied	Can’t write to .gitnexus/	Check file permissions

---

Best Practices

Before Indexing

1. Ensure .gitignore is clean - Exclude build artifacts
2. Commit or stash changes - Cleaner index state
3. Close other apps - Free up memory for large repos

After Indexing

1. Verify status - Run gitnexus status
2. Test MCP tools - Try query tool in your editor
3. Re-index on major changes - After large refactors or branch switches

Regular Maintenance

1. Re-index periodically - Run gitnexus analyze after big changes
2. Check for updates - npm update -g gitnexus (if installed globally)
3. Clean old indexes - Delete indexes for archived projects