Troubleshooting

Installation

pip install ranex fails

Common causes:

• No wheel for your environment
  • Upgrade pip.
  • Try a supported Python version.
• Build dependencies missing (source build)
  • Source builds require a Rust toolchain and Python development headers.

CLI

ranex: command not found

• Confirm you activated the correct virtual environment.
• Reinstall: pip install --upgrade ranex

ranex version works but other commands fail

• Ensure you are running inside a valid project directory.
• Use --project-root explicitly to point at your project.

Atlas

artifacts_found=0

• Ensure you ran ranex atlas scan in the correct project.
• Ensure your project actually contains Python files.
• Ensure .ranexignore is not excluding everything.

Database problems

If you suspect the index is corrupted, you can delete .ranex/atlas.sqlite and re-scan.

Slow scans

• Add high-churn or irrelevant directories to .ranexignore.
• Reduce scan scope (for example by scanning only a subproject).

Firewall

Firewall blocks a new dependency you need

• Add the package to .ranex/firewall.yaml under allowed_packages.
• Keep the policy under version control so changes are reviewed.

Firewall policy YAML fails to load

• Validate that the YAML is syntactically correct.
• Run ranex firewall info --json to see which policy source is active.

MCP server

MCP server sees the wrong project

• Ensure RANEX_PROJECT_ROOT is set to the intended absolute path.

No tools available in the client

• Ensure the client is configured to run ranex-mcp-server over stdio.
• Ensure the binary is executable and on PATH.