Troubleshooting

Hit a snag? Here’s how to get unstuck fast.

Your AI coding tool can help too. Use these docs to troubleshoot with AI.

Installation

OpenGrep not found

Symptom: switch-trust scan warns that the scan is incomplete, and lists opengrep with the reason OpenGrep binary not foundCause: OpenGrep is required for scan functionality but not installed. From version 1.8.0, the scan exits with code 26 after writing its results.Fix: Install OpenGrep using the shell installer:

curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash

After installation, verify:

opengrep --version

See OpenGrep installation for manual installation or other options.

Which API key do I need?

switch-trust scan uses an LLM to analyze your agent code. Run switch-trust init and provide an API key from one of these providers:

Google Gemini - Get your key from aistudio.google.com/apikey (free tier available)
OpenAI - Get your key from platform.openai.com/api-keys
Anthropic - Get your key from console.anthropic.com/settings/keys

You only need one key to get started.

Unsupported Python version

Symptom: pip install switch-trust-cli fails with an error that the package requires a different Python version, or with No matching distribution found for datafog==4.4.0.Cause: You’re running a Python version older than 3.11, or 3.14 or later. Switch Trust CLI installs on Python 3.11 to 3.13.Fix:

Install Python 3.11, 3.12 or 3.13 from python.org
Verify: python3 --version
Reinstall Switch Trust CLI: pip install switch-trust-cli

ImportError naming the full extra

Symptom: A command stops with an ImportError such as garak is required for garak probes and detectors. Install it with: pip install switch-trust-cli[full], or the same message for transformers.Cause: Garak probes, toxicity detection, and HuggingFace models rely on machine-learning backends that aren’t part of the standard install. They live in the optional full extra, which keeps the default download roughly 2 GB smaller.Fix: Install the extra. Quote it — in zsh, the default shell on macOS, an unquoted [full] is a glob pattern and the command fails with no matches found:

pip install 'switch-trust-cli[full]'

Command not found after install

Symptom: switch-trust: command not found after installingCause: Most often, the virtual environment you installed into isn’t active — a new terminal session starts outside it. Less often, you installed outside a virtual environment and the install location isn’t on your PATH.Fix:If you installed in a virtual environment, reactivate it from the directory you created it in:

source .venv/bin/activate

Do this in each new terminal session before you run switch-trust.If you installed outside a virtual environment, add the install location to your PATH:

Find where pip installed it: pip show switch-trust-cli
Add that location to your PATH in ~/.bashrc or ~/.zshrc:
export PATH="$PATH:/path/to/bin"
Reload: source ~/.bashrc (or restart terminal)

Alternative: install with pipx. It handles PATH for you and needs no activation step, at the cost of installing another tool:

brew install pipx  # macOS
pipx ensurepath
pipx install switch-trust-cli

How do I view Switch Trust CLI logs?

Every run writes a log file, switch_trust_<timestamp>.log by default. Use --log to choose the path:

switch-trust scan /path/to/agent --log scan.log
switch-trust eval run --model my-agent --log eval.log

To capture console output as well, redirect stderr:

switch-trust scan /path/to/agent 2> scan-console.log

Increase verbosity with environment variable:

export LOG_LEVEL=DEBUG
switch-trust scan /path/to/agent

Scan

No scannable targets found

Symptom: Scan stops immediately with an error reading No scannable targets foundCause: Nothing under the path qualified for scanning. A file is picked up only if it’s a requirements.txt, or a .py file that imports a supported framework — framework imports are what put a file in scope, not just the extension.Fix:

Verify your agent code imports a supported framework
Check you’re scanning the correct directory
Make sure files have a .py extension. __init__.py is always skipped, so scanning a package whose only file is __init__.py finds nothing

If you pointed at a single file, the same rule applies to that one file. Scan the directory above it to pick up its requirements.txt and framework-importing siblings.

Framework not detected

Symptom: Files scanned but framework shows as “unknown”Cause: Import pattern not recognizedFix: Check your import matches the supported frameworks list exactly

Missing API key: AI reasoning disabled

Symptom: Scan runs but no AI reasoning or findingsCause: No GENERATOR_MODEL API key configuredFix: Run switch-trust init to configure your API key

Timeout errors: ADK_LOOP_TIMEOUT_SECS exceeded

Symptom: Scan fails with timeout errorCause: Large codebase or long AI reasoning timeFix: Increase timeout in your environment:

export ADK_LOOP_TIMEOUT_SECS=600  # 10 minutes
switch-trust scan /path/to/agent

Or use a faster GENERATOR_MODEL like gemini:gemini-3.1-flash-lite in ~/.switch-trust/.env

Why aren't my files being scanned?

Switch Trust CLI only analyzes Python files that import one of the supported frameworks. Files without these imports are skipped.Check that your agent code:

Uses Python (not TypeScript/JavaScript)
Imports at least one supported framework
Has valid Python syntax

How long does a scan take?

Scan time depends on:

Codebase size: Number of Python files to analyze
AI reasoning: GENERATOR_MODEL speed (Gemini Flash is fastest, GPT-4 slowest)
Findings volume: More potential issues = more LLM calls

Typical times:

Small agent (1-5 files): 30 seconds - 2 minutes
Medium project (10-50 files): 2-10 minutes
Large codebase (100+ files): 10-30 minutes

To speed up: Use a faster GENERATOR_MODEL like gemini:gemini-3.1-flash-lite in ~/.switch-trust/.env

Can I use Switch Trust CLI in CI/CD?

Yes! See our CI/CD integration guide for GitHub Actions, GitLab CI, and CircleCI examples.

Eval

Missing config.json

Symptom: “Config file not found”Cause: No config file at ~/.switch-trust/config.jsonFix: Create a minimal config file at ~/.switch-trust/config.json:

{
  "models": [
    {
      "id": "my-agent",
      "type": "adk",
      "name": "My Agent",
      "host": "http://localhost:8000"
    }
  ]
}

See Configuration for all options.

Invalid model type

Symptom: “Unsupported model type”Cause: Model type not in supported listFix: Use one of these supported model types:

adk - Google ADK agents
openai_agent - OpenAI Agents SDK
langchain - LangChain agents
crewai - CrewAI agents

Check your model definition in config.json and update the type field.

Connection refused: Agent not running

Symptom: Cannot connect to agent HTTP endpointCause: Agent not running or wrong URLFix:

Start your agent server
Confirm the server is listening at the host from your eval config — any HTTP response, even a 404, means it’s reachable, while a connection error means it isn’t running:
curl -i http://localhost:8000
Check the host field in your eval config matches the URL of your agent
Ensure there’s no firewall blocking the connection

Empty results: No evaluations attached

Symptom: Eval runs but produces no resultsCause: No model-evaluation assignmentsFix: Attach evaluations to your model:

switch-trust eval model-evaluations attach \
  --model my-agent \
  --eval eval-llm01-fixed

List available evaluations with switch-trust eval evaluations list to see what you can attach.

Can I add custom evaluations?

Yes! Create custom evaluations in your config.json:Message collection approach:

{
  "evaluations": [{
    "id": "eval-custom-scope",
    "type": "message_collection",
    "name": "Scope boundary test",
    "message_collection_id": "mc-custom",
    "detector_id": "det-custom"
  }],
  "message_collections": [{
    "id": "mc-custom",
    "type": "in-memory",
    "prompts": ["Your test prompt 1", "Your test prompt 2"]
  }],
  "detectors": [{
    "id": "det-custom",
    "type": "model",
    "model_id": "model-judge",
    "prompt": "Your judge instructions..."
  }]
}

Then attach to your model with switch-trust eval model-evaluations attach.See Configuration for more examples.

Still stuck? Contact us at support@switchagents.ai

Overview

Switch Trust Scan

Switch Trust Eval

Guides

Reference

Resources

Troubleshooting

Installation

Scan

Eval