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

# Troubleshooting

> Common issues and solutions for Refrain.

## Installation issues

<AccordionGroup>
  <Accordion title="Node.js version error">
    Refrain requires Node.js 18 or later. Check your version:

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

    If it's below 18, update Node.js using [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm), or download from [nodejs.org](https://nodejs.org/).
  </Accordion>

  <Accordion title="Permission error during global install">
    If `npm install -g` fails with permission errors, either:

    * Use `npx @refrainai/cli` instead (no global install needed)
    * Fix npm permissions: [npm docs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
  </Accordion>

  <Accordion title="Browser binary not found">
    Refrain bundles a Chromium binary automatically. If it's not found, try reinstalling:

    ```bash theme={null}
    npm install -g @refrainai/cli
    ```

    If behind a corporate proxy, ensure the proxy allows downloading from Playwright's CDN.
  </Accordion>
</AccordionGroup>

## AI provider issues

<AccordionGroup>
  <Accordion title="'API key not set' error">
    Ensure the appropriate environment variable is exported for your provider:

    ```bash theme={null}
    # Anthropic (default)
    export ANTHROPIC_API_KEY="sk-ant-..."

    # OpenAI
    export OPENAI_API_KEY="sk-..."
    ```

    See [AI Provider Setup](/guides/ai-setup) for all provider variables.
  </Accordion>

  <Accordion title="Rate limit errors (429)">
    You've hit the provider's rate limit. Options:

    * Wait and retry — Refrain automatically retries with exponential backoff
    * Use a different model or provider
    * Contact your AI provider to increase limits
  </Accordion>

  <Accordion title="Model ID not found">
    Double-check the model ID matches your provider. Common examples:

    * Anthropic: `claude-sonnet-4-6`
    * OpenAI: `gpt-4o`
    * Google: `gemini-2.5-pro`
    * Bedrock: `anthropic.claude-sonnet-4-6-v1:0`
    * Vertex: `claude-sonnet-4-6@20250514`
  </Accordion>
</AccordionGroup>

## Generation issues

<AccordionGroup>
  <Accordion title="AI gets stuck or goes in circles">
    * Press **Enter** to pause and provide guidance
    * Add more detail to `context.md` about the target page
    * Try a more specific `--goal`
    * Increase `--max-iterations` if the workflow is long
  </Accordion>

  <Accordion title="AI explores the wrong pages">
    Add navigation hints to `context.md`:

    ```markdown theme={null}
    - After login, go directly to /settings (don't click on the dashboard)
    - The export button is under the "Reports" tab, not the "Dashboard" tab
    ```
  </Accordion>

  <Accordion title="Goal not achieved">
    Check the generated report for details on where AI stopped. Common causes:

    * Insufficient context — add more detail to `context.md`
    * Bot detection — try `--stealth` mode
    * Complex multi-step workflow — break into smaller goals
  </Accordion>

  <Accordion title="Bot detection blocking the browser">
    Use stealth mode to apply anti-detection patches:

    ```bash theme={null}
    npx @refrainai/cli generate -- \
      --url "https://example.com" --goal "..." --output ./flow.yaml \
      --stealth
    ```

    Some sites may also require `--proxy` to route through a residential proxy.
  </Accordion>
</AccordionGroup>

## Execution issues

<AccordionGroup>
  <Accordion title="Selector resolution fails">
    The UI may have changed since the runbook was generated. Options:

    1. Run with `--self-heal` to get AI repair suggestions
    2. Run with `--headless false` to see what the page looks like
    3. Use `--screenshots` to capture the page state at each step
  </Accordion>

  <Accordion title="Variables not being resolved">
    Check the variable's `source` type:

    * `prompt` — asks interactively at the CLI
    * `env` — reads from environment variables (ensure they're exported)
    * `context` — requires a `--context` file
    * `fixed` — the value should be in the runbook definition
    * `secrets` — requires a `--secrets` file
  </Accordion>

  <Accordion title="Timeout errors">
    The page may be slow to load. Options:

    * Increase `--step-delay` to give pages more time between steps
    * Add a `wait` step in the runbook before the failing step
    * Check network connectivity to the target site
  </Accordion>

  <Accordion title="Download files not appearing">
    Ensure `--output-dir` is set:

    ```bash theme={null}
    npx @refrainai/cli execute -- \
      --runbook ./flow.yaml \
      --output-dir ./downloads
    ```

    The directory is created automatically if it doesn't exist.
  </Accordion>
</AccordionGroup>

## Approval & notification issues

<AccordionGroup>
  <Accordion title="Slack buttons show 'This didn't work'">
    The Interactivity Request URL is invalid or unreachable. Verify the URL in your Slack App's Interactivity settings. See [Approval & Notifications](/guides/approval-and-notifications) for setup details.
  </Accordion>

  <Accordion title="Approval times out">
    The callback is not reaching the executor. Verify that the callback endpoint is accessible from the internet and the Slack App's Request URL is correctly configured.
  </Accordion>

  <Accordion title="'not_in_channel' error">
    The bot hasn't been invited to the Slack channel. Run `/invite @your-bot-name` in the target channel.
  </Accordion>
</AccordionGroup>

## Debugging tools

When troubleshooting, these flags are your best friends:

| Flag                  | What it does                                    |
| --------------------- | ----------------------------------------------- |
| `--headless false`    | Show the browser window to see what's happening |
| `--screenshots <dir>` | Save a screenshot after each step               |
| `--report`            | Generate a detailed Markdown execution report   |
| `--debug`             | Print debug output to the console               |

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --headless false \
  --screenshots ./debug-screenshots \
  --report \
  --debug
```

## Getting help

* [CLI Reference](/cli/overview) — All commands and options
* [YAML Reference](/yaml/overview) — Runbook schema documentation
* [Plans & Pricing](/concepts/plan-tiers) — Feature availability by plan