> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flintai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fast fixes for installation, scan, and eval

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

<Tip>
  **Your AI coding tool can help too.** [Use these docs](/flintai/cli/resources/use-these-docs) to troubleshoot with AI.
</Tip>

<h2 id="installation">
  Installation
</h2>

<Accordion title="OpenGrep not found">
  **Symptom:** Warning message `OpenGrep not found — skipping pattern scan` when running `flintai scan`

  **Cause:** OpenGrep is required for scan functionality but not installed

  **Fix:** Install OpenGrep using the shell installer:

  <Tabs>
    <Tab title="Linux / macOS">
      ```bash theme={null}
      curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash
      ```
    </Tab>

    <Tab title="Windows PowerShell">
      ```powershell theme={null}
      irm https://raw.githubusercontent.com/opengrep/opengrep/main/install.ps1 | iex
      ```
    </Tab>
  </Tabs>

  After installation, verify:

  ```bash theme={null}
  opengrep --version
  ```

  See [OpenGrep installation](https://github.com/opengrep/opengrep#installation) for manual installation or other options.
</Accordion>

<Accordion title="Which API key do I need?">
  `flintai scan` uses an LLM to analyze your agent code. Run `flintai init` and provide an API key from one of these providers:

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

  You only need one key to get started.
</Accordion>

<Accordion title="Python version mismatch: Requires Python 3.13+">
  **Symptom:** Error says "Requires Python 3.13+"

  **Cause:** You're running an older Python version.

  **Fix:**

  1. Install Python 3.13+ from [python.org](https://python.org)
  2. Verify: `python3.13 --version`
  3. Reinstall Flint AI CLI: `pip install flintai-cli`
</Accordion>

<Accordion title="Command not found after install">
  **Symptom:** `flintai: command not found` after installing

  **Cause:** Install location not in your PATH

  **Fix:**

  **With pip:**

  1. Find where pip installed it: `pip show flintai-cli`
  2. Add that location to your PATH in `~/.bashrc` or `~/.zshrc`:
     ```bash theme={null}
     export PATH="$PATH:/path/to/bin"
     ```
  3. Reload: `source ~/.bashrc` (or restart terminal)

  **With pipx (recommended):**
  Pipx automatically handles PATH. Install pipx first:

  ```bash theme={null}
  brew install pipx  # macOS
  pipx ensurepath
  pipx install flintai-cli
  ```
</Accordion>

<Accordion title="How do I view Flint AI CLI logs?">
  Flint AI CLI outputs logs to stderr during execution. To save logs to a file:

  ```bash theme={null}
  flintai scan /path/to/agent 2> scan.log
  ```

  For eval runs:

  ```bash theme={null}
  flintai eval run --model my-agent 2> eval.log
  ```

  Increase verbosity with environment variable:

  ```bash theme={null}
  export LOG_LEVEL=DEBUG
  flintai scan /path/to/agent
  ```
</Accordion>

<h2 id="scan">
  Scan
</h2>

<Accordion title="Empty output: No agents found">
  **Symptom:** Scan completes but shows `agents_found: 0`

  **Cause:** No framework imports detected in your Python files

  **Fix:**

  1. Verify your agent code imports a [supported framework](/flintai/cli/resources/faq#which-frameworks-does-flintai-cli-support)
  2. Check you're scanning the correct directory
  3. Make sure files have `.py` extension
</Accordion>

<Accordion title="Framework not detected">
  **Symptom:** Files scanned but framework shows as "unknown"

  **Cause:** Import pattern not recognized

  **Fix:** Check your import matches the [supported frameworks list](/flintai/cli/resources/faq#which-frameworks-does-flintai-support) exactly
</Accordion>

<Accordion title="Missing API key: AI reasoning disabled">
  **Symptom:** Scan runs but no AI reasoning or findings

  **Cause:** No GENERATOR\_MODEL API key configured

  **Fix:** Run `flintai init` to configure your API key
</Accordion>

<Accordion title="Timeout errors: ADK_LOOP_TIMEOUT_SECS exceeded">
  **Symptom:** Scan fails with timeout error

  **Cause:** Large codebase or long AI reasoning time

  **Fix:** Increase timeout in your environment:

  ```bash theme={null}
  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`
</Accordion>

<Accordion title="Why aren't my files being scanned?">
  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](/flintai/cli/resources/faq#which-frameworks-does-flintai-support)
  * Has valid Python syntax
</Accordion>

<Accordion title="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 `~/.flintai/.env`
</Accordion>

<Accordion title="Can I use Flint AI CLI in CI/CD?">
  Yes! See our [CI/CD integration guide](/flintai/cli/guides/ci-cd-integration) for GitHub Actions, GitLab CI, and CircleCI examples.
</Accordion>

<h2 id="eval">
  Eval
</h2>

<Accordion title="Missing config.json">
  **Symptom:** "Config file not found"

  **Cause:** No config file at `~/.flintai/config.json`

  **Fix:** Create a minimal config file at `~/.flintai/config.json`:

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

  See [Configuration](/flintai/cli/eval/eval-configuration) for all options.
</Accordion>

<Accordion title="Invalid model type">
  **Symptom:** "Unsupported model type"

  **Cause:** Model type not in supported list

  **Fix:** 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.
</Accordion>

<Accordion title="Connection refused: Agent not running">
  **Symptom:** Cannot connect to agent HTTP endpoint

  **Cause:** Agent not running or wrong URL

  **Fix:**

  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
</Accordion>

<Accordion title="Empty results: No evaluations attached">
  **Symptom:** Eval runs but produces no results

  **Cause:** No model-evaluation assignments

  **Fix:** Attach evaluations to your model:

  ```bash theme={null}
  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.
</Accordion>

<Accordion title="Can I add custom evaluations?">
  Yes! Create custom evaluations in your `config.json`:

  **Message collection approach:**

  ```json theme={null}
  {
    "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](/flintai/cli/eval/eval-configuration) for more examples.
</Accordion>

***

Still stuck? Contact us at [support@flintai.dev](mailto:support@flintai.dev)