Installation Troubleshooting

Use this page when 10xGraph fails before your app even starts: package install problems, import errors, missing dependencies, or broken Python environments.

Troubleshooting flow

flowchart TD
    A[Install or import fails] --> B[Check Python version]
    B --> C[Check active virtual environment]
    C --> D[Check installed packages]
    D --> E[Check optional extras and provider deps]
    E --> F[Retry import or command]

Issue: pip install fails

Symptoms

• install command exits with dependency errors
• build tools or package resolution fails

Likely causes

• unsupported Python version
• stale virtual environment
• conflicting previously installed packages

Fix

• use Python 3.12+
• create a fresh virtual environment
• reinstall inside the fresh environment

Issue: agentflow command is not found

Symptoms

• shell says command not found

Likely causes

• CLI package not installed
• virtual environment not activated
• shell path points at a different Python environment

Fix

pip install 10xscale-agentflow-cli
which agentflow
agentflow version
agentflow audit          # interpreter, packages, project config, and port

If which agentflow points somewhere unexpected, activate the correct environment first. agentflow audit reports the interpreter it runs under and the installed CLI and core versions, so it is the fastest way to spot a wrong environment or a CLI/core version skew.

Issue: imports fail even after install

Symptoms

• ModuleNotFoundError
• ImportError during graph import or script execution

Likely causes

• package installed in a different environment
• optional dependency not installed
• import path in your code is outdated

Fix

• verify python -c "import tenxgraph; print(tenxgraph.__file__)"
• verify you are using current import paths in docs and code
• install optional extras when needed

Issue: optional features fail at runtime

Symptoms

• a feature works until you use Postgres, A2A, or another optional integration
• runtime error says a package is missing

Likely cause

• optional dependencies were not installed

Fix

Install the required extras or packages for the feature you are actually using.

Issue: environment variables appear to be ignored

Symptoms

• provider keys seem unset
• app behaves as if .env was not loaded

Likely causes

• env field missing from 10xgraph.json
• .env file in the wrong directory
• variables exported in one shell but server started from another

Fix

• verify 10xgraph.json points to the correct .env
• verify the file exists relative to the project root
• test with a direct Python import from the same shell session

Related docs

• Installation
• Configure 10xgraph.json
• Environment Variables
• Error Codes Reference

What you learned

• How to isolate installation problems to Python version, environment activation, missing packages, or missing config.