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:
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.
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: Error says “Requires Python 3.13+”Cause: You’re running an older Python version.Fix:
  1. Install Python 3.13+ from python.org
  2. Verify: python3.13 --version
  3. Reinstall Flint AI CLI: pip install flintai-cli
Symptom: flintai: command not found after installingCause: Install location not in your PATHFix:With pip:
  1. Find where pip installed it: pip show flintai-cli
  2. Add that location to your PATH in ~/.bashrc or ~/.zshrc: 
    export PATH="$PATH:/path/to/bin"
  3. Reload: source ~/.bashrc (or restart terminal)
With pipx (recommended): Pipx automatically handles PATH. Install pipx first:
brew install pipx  # macOS
pipx ensurepath
pipx install flintai-cli
Flint AI CLI outputs logs to stderr during execution. To save logs to a file:
flintai scan /path/to/agent 2> scan.log
For eval runs:
flintai eval run --model my-agent 2> eval.log
Increase verbosity with environment variable:
export LOG_LEVEL=DEBUG
flintai scan /path/to/agent

​
Scan

Symptom: Scan completes but shows agents_found: 0Cause: No framework imports detected in your Python filesFix:
  1. Verify your agent code imports a supported framework
  2. Check you’re scanning the correct directory
  3. Make sure files have .py extension
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:
export ADK_LOOP_TIMEOUT_SECS=600  # 10 minutes
flintai scan /path/to/agent
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:
{
  "models": [
    {
      "id": "my-agent",
      "type": "adk",
      "name": "My Agent",
      "host": "http://localhost:8000"
    }
  ]
}
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. Verify it’s accessible: curl http://localhost:8000/health (or your agent’s endpoint)
  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:
flintai eval model-evaluations attach \
  --model my-agent \
  --evaluation eval-llm01-fixed
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:
{
  "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 flintai eval model-evaluations attach.See Configuration for more examples.
Still stuck? Contact us at info@flintai.dev