Skip to main content

Installation troubleshooting

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

Troubleshooting flow​

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 agentflow; print(agentflow.__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 agentflow.json
  • .env file in the wrong directory
  • variables exported in one shell but server started from another

Fix

  • verify agentflow.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

What you learned​

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