Graphify Docs

Appearance

Troubleshooting ​

Fresh

Installation Issues ​

command not found: graphify ​

Cause: pip installed the package but its binary directory is not on PATH.

Fix:

bash
# Find where pip installs binaries
python3 -m site --user-base   # e.g., /Users/you/.local

# Add to PATH (bash/zsh)
export PATH="$PATH:/Users/you/.local/bin"

# Or run directly
python3 -m graphify --version

pip install graphify installed the wrong package ​

Cause: PyPI has a different package named graphify.

Fix:

bash
pip uninstall graphify
pip install graphifyy    # double-y

Python version error ​

Cause: Graphify requires Python 3.10+.

Fix:

bash
python3 --version   # Check version
# If < 3.10, install newer Python via pyenv or official installer
pip3.11 install graphifyy   # Use specific version

Build Issues ​

Build hangs or takes very long ​

Cause: Large PDF or documentation files triggering slow LLM extraction.

Fix:

bash
# Add large files to .graphifyignore
echo "data/large-report.pdf" >> .graphifyignore
echo "docs/archive/" >> .graphifyignore

# Then rebuild
/graphify . --update

graph.json not updating after changes ​

Cause: Running without --update forces a full rebuild even for unchanged files, but the cache may be stale.

Fix:

bash
# Force full rebuild
rm -rf graphify-out/cache/
/graphify .

GRAPH_REPORT.md shows no God Nodes ​

Cause: The graph has too few nodes for Leiden clustering to find hubs.

Fix: This is normal for very small projects (< 10 files). Add more source files or run --mode deep to generate more inferred edges.

Query Issues ​

/graphify query returns no results ​

Cause: Graph may be empty or the query term doesn't match any node names.

Fix:

bash
# Check graph has content
cat graphify-out/GRAPH_REPORT.md | head -30

# Try broader terms
/graphify query "main"
/graphify query "function"

/graphify path "A" "B" returns "No path found" ​

Cause: The two nodes are in disconnected communities, or one/both node names are wrong.

Fix:

bash
# Check node names from the report (case-sensitive)
cat graphify-out/GRAPH_REPORT.md | grep -i "nodename"

# Use explain to confirm a node exists
/graphify explain "NodeName"

Platform Integration Issues ​

Claude Code not consulting the graph ​

Cause: The PreToolUse hook may not be installed or the CLAUDE.md directive is missing.

Fix:

bash
# Reinstall
graphify claude uninstall
graphify claude install

# Verify CLAUDE.md has a Graphify section
grep -l "graphify" CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null

Hook not firing after commits ​

Cause: Git hooks may not have execute permission.

Fix:

bash
ls -la .git/hooks/post-commit
chmod +x .git/hooks/post-commit
chmod +x .git/hooks/post-checkout

Watch Mode Issues ​

Watch mode not detecting changes ​

Cause: The watched path may be wrong, or the filesystem event system is overwhelmed.

Fix:

bash
# Restart with explicit path
/graphify ./src --watch

# On Linux, increase inotify limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Getting Help ​