Skip to main content
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

Symptom: Warning message OpenGrep not found — skipping pattern scan when running flintai scanCause: OpenGrep is required for scan functionality but not installedFix: Install OpenGrep using the shell installer:
After installation, verify:
See OpenGrep installation for manual installation or other options.
flintai scan uses an LLM to analyze your agent code. Run flintai init and provide an API key from one of these providers:You only need one key to get started.
Symptom: pip install flintai-cli fails with an error that the package requires a different Python version.Cause: You’re running a Python version older than 3.11.Fix:
  1. Install Python 3.11 or later from python.org
  2. Verify: python3 --version
  3. Reinstall Flint AI CLI: pip install flintai-cli
Symptom: A command stops with an ImportError such as garak is required for garak probes and detectors. Install it with: pip install flintai-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:
Symptom: flintai: 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:
Do this in each new terminal session before you run flintai.If you installed outside a virtual environment, add the install location to your PATH:
  1. Find where pip installed it: pip show flintai-cli
  2. Add that location to your PATH in ~/.bashrc or ~/.zshrc:
  3. 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:
Every run writes a log file, flintai_<timestamp>.log by default. Use --log to choose the path:
To capture console output as well, redirect stderr:
Increase verbosity with environment variable:

​
Scan

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:
  1. Verify your agent code imports a supported framework
  2. Check you’re scanning the correct directory
  3. 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.
Symptom: Files scanned but framework shows as “unknown”Cause: Import pattern not recognizedFix: Check your import matches the supported frameworks list exactly
Symptom: Scan runs but no AI reasoning or findingsCause: No GENERATOR_MODEL API key configuredFix: Run flintai init to configure your API key
Symptom: Scan fails with timeout errorCause: Large codebase or long AI reasoning timeFix: Increase timeout in your environment:
Or use a faster GENERATOR_MODEL like gemini:gemini-3.1-flash-lite in ~/.flintai/.env
Flint AI 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
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 ~/.flintai/.env
Yes! See our CI/CD integration guide for GitHub Actions, GitLab CI, and CircleCI examples.

​
Eval

Symptom: “Config file not found”Cause: No config file at ~/.flintai/config.jsonFix: Create a minimal config file at ~/.flintai/config.json:
See Configuration for all options.
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.
Symptom: Cannot connect to agent HTTP endpointCause: Agent not running or wrong URLFix:
  1. Start your agent server
  2. 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:
  3. Check the host field in your eval config matches your agent’s URL
  4. Ensure there’s no firewall blocking the connection
Symptom: Eval runs but produces no resultsCause: No model-evaluation assignmentsFix: Attach evaluations to your model:
List available evaluations with flintai eval evaluations list to see what you can attach.
Yes! Create custom evaluations in your config.json:Message collection approach:
Then attach to your model with flintai eval model-evaluations attach.See Configuration for more examples.
Still stuck? Contact us at support@flintai.dev