Troubleshooting
Common Graphify issues and their solutions.
On this page
Troubleshooting
Common Graphify issues and their solutions.
🚨 Quick Diagnosis
1# 1. Check installation
2graphify --version
3
4# 2. Check graph exists
5ls -lh graphify-out/graph.json
6
7# 3. Check activity signaling
8cat graphify-out/.graphify-activity.json
9
10# 4. Test basic query
11mkdir -p graphify-out && touch graphify-out/.graphify-activity
12graphify query "test"
📋 Common Issues
1. graphify: command not found
Cause: graphify not in PATH after uv tool install.
Fix:
1# Option 1: Restart shell
2exec $SHELL
3
4# Option 2: Add to PATH manually
5export PATH="$HOME/.local/bin:$PATH"
6echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
7
8# Option 3: Use full path
9~/.local/bin/graphify --version
10
11# Option 4: Reinstall with uv
12uv tool install graphifyy --force
2. no LLM API key found
Cause: Running full graph without API key.
Fix:
1# Use code-only mode (no API key needed)
2graphify . --code-only
3graphify update . --code-only
4graphify query "question" --code-only
5
6# OR set API key
7export GEMINI_API_KEY="your-key"
8# Then run without --code-only
9graphify .
3. graph.json missing or < 500 bytes
Cause: Graph built on empty repo, or initial build ran before code existed.
Fix:
1# Signal activity
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# Full rebuild (not update)
5graphify . --code-only
6
7# Verify
8ls -lh graphify-out/graph.json
9# Should be > 500 KB (3.3 MB in this project)
4. Query returns empty / “I don’t know”
Cause: Graph is stale, empty, or query too vague.
Fix:
1# 1. Rebuild
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3graphify update . --code-only
4
5# 2. Use specific terms from codebase
6graphify query "how does yt-to-content-v2.py work?"
7# NOT: "how does the script work?"
8
9# 3. Check graph has content
10graphify query "project overview"
5. graphify path A B returns “no path found”
Cause: Nodes not in same graph, or graph stale.
Fix:
1# 1. Rebuild
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3graphify update . --code-only
4
5# 2. Verify both nodes exist
6graphify explain A
7graphify explain B
8
9# 3. Try reverse direction
10graphify path B A
11
12# 4. Use qualified IDs
13graphify path path/to/A.py path/to/B.py
6. graphify explain X returns “node not found”
Cause: Wrong node ID, or symbol not in graph.
Fix:
1# 1. Find correct ID
2graphify query "what is the node ID for mergeParams?"
3
4# 2. Use qualified ID
5graphify explain scripts/dictionary/yt-to-content-v2.py:mergeParams
6
7# 3. Rebuild if symbol missing
8graphify update . --code-only
7. graphify . fails with “Model not found”
Cause: Local LLM model not downloaded.
Fix:
1graphify install
2# Downloads ~2 GB model to ~/.cache/graphify/
3# Run once per machine
8. Build hangs / takes too long
Cause: Large codebase, low memory, or API rate limit.
Fix:
1# Use code-only (faster, no API)
2graphify . --code-only
3
4# Kill and retry with more memory
5# Close other apps
6# Increase swap if needed
9. Graph has stale references (deleted files still shown)
Cause: graphify update . is incremental; doesn’t remove deleted nodes.
Fix:
1# Full rebuild (removes stale nodes)
2graphify . --code-only
3# NOT: graphify update . --code-only
10. permission denied or file access errors
Cause: Files in .gitignore or permission issues.
Fix:
1# Check .graphifyignore
2cat .graphifyignore
3
4# Override with --no-gitignore
5graphify . --code-only --no-gitignore
6
7# Check file permissions
8ls -la path/to/file
🔧 Environment Issues
Python Version
1# Graphify requires Python 3.10+
2python3 --version
3# If < 3.10: install newer Python
4uv python install 3.11
5uv python pin 3.11
uv Not Found
1# Install uv
2curl -LsSf https://astral.sh/uv/install.sh | sh
3source ~/.bashrc
Disk Space
1# Check space
2df -h .
3# Need ~2 GB for model + graph
4
5# Clean up
6rm -rf ~/.cache/graphify/old-versions
7graphify install # Re-downloads model
🐛 Debug Mode
1# Verbose output
2graphify -v query "question"
3graphify -v . --code-only
4graphify -v update . --code-only
5
6# Check logs
7# Graphify logs to stderr; no separate log file
📞 Getting Help
- Check this guide — Most issues covered above
- Run with
-v— Verbose output shows what’s happening - Rebuild from scratch —
graphify . --code-onlyfixes 90% of issues - Check Graphify GitHub — Issues/discussions for bugs
Next Steps
- Commands - Reference for all commands
- Node IDs - Understanding identifiers
- Edge Types - Relationship types