Troubleshooting

Troubleshooting

Installation Issues

tree-sitter build fails on install

tree-sitter needs a C++ compiler to compile native parser modules.

Solution:

• Linux: sudo apt install build-essential
• macOS: xcode-select --install
• Windows: Install "Desktop development with C++" via the Visual Studio Installer

After installing the toolchain, reinstall:

npm uninstall -g codebase-vis
npm install -g codebase-vis

Permission errors on global install

Solution: Use one of:

# Option 1: Use npx instead
npx codebase-vis <command>

# Option 2: Fix npm permissions
sudo npm install -g codebase-vis

# Option 3: Use a version manager (recommended)
nvm install 20 && nvm use 20
npm install -g codebase-vis

Runtime Issues

Port already in use

Error: listen EADDRINUSE :::3000

Solution: Use a different port:

codebase-vis serve --port 4000

"graph.json not found"

Error: graph.json not found in codebase-out/

Solution: Run codebase-vis generate first to create the graph data.

No files found during generate

Generated: 0 files

Solution:

1. Check your .agentignore file — you might be excluding the target directory
2. Run with --verbose to see which files are being processed
3. Verify your project has files with supported extensions (.js, .ts, .py, .cpp, .html, .css, .rs, .go, .java)
4. Check if files are larger than 2 MB (they're skipped automatically)

Visualizer shows no nodes

The graph loads but appears empty.

Solutions:

1. Zoom out — the nodes might be clustered
2. Check the community legend — some communities might be toggled off
3. Check if dependencies/entities filters are hiding everything
4. Run codebase-vis query <any-file> to verify the graph has data

"No path found" in path command

No path found between source and target

Solution: The two files have no dependency relationship. Try different files, or use query to see each file's connections.

Explain command fails

Error: 401 Unauthorized

Solution: Your Groq API key is missing or invalid.

• Run codebase-vis explain --reset to re-enter your key
• Or set GROQ_API_KEY environment variable

Error: 429 Too Many Requests

Solution: You're hitting rate limits.

• Lower --rpm (default 30)
• Lower --concurrency (default 2)
• Run codebase-vis explain --retry to retry only failed clusters

Visualizer Issues

graph.html shows blank page

Check the browser console (F12) for errors.

Solutions:

1. Make sure graph.json is in the same directory as graph.html
2. If opening directly (not via serve), some browsers block fetch() from file:// protocol — use codebase-vis serve instead
3. Clear browser cache and reload

Graph layout is messy

The ForceAtlas2 physics take a few seconds to settle. If it's still messy:

Solutions:

1. Let the physics simulation run longer (it stabilizes over time)
2. Drag nodes to manually adjust
3. Zoom in/out to find a good viewing level

Cache Issues

generate seems to skip files that should be re-parsed

Solution: Delete .cache.json in codebase-out/ and re-run generate. The cache will be rebuilt from scratch.

Cache file is corrupted

Solution: Delete codebase-out/.cache.json and re-run generate. A fresh cache will be created.

General

How do I completely reset?

codebase-vis clean   # Deletes codebase-out/

Then re-run codebase-vis generate.

How do I see what version I have?

codebase-vis --version

How do I report a bug?

Open an issue at github.com/Arham-Qureshi/codebase-vis/issues.