> ## 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.

# トラブルシューティング

> Refrain のよくある問題と解決策。

## インストール関連

<AccordionGroup>
  <Accordion title="Node.js のバージョンエラー">
    Refrain には Node.js 18 以降が必要です。バージョンを確認してください：

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

    18 未満の場合は [nvm](https://github.com/nvm-sh/nvm)、[fnm](https://github.com/Schniz/fnm)、または [nodejs.org](https://nodejs.org/) から Node.js を更新してください。
  </Accordion>

  <Accordion title="グローバルインストール時のパーミッションエラー">
    `npm install -g` がパーミッションエラーで失敗する場合：

    * `npx @refrainai/cli` を使用（グローバルインストール不要）
    * npm のパーミッションを修正：[npm ドキュメント](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
  </Accordion>

  <Accordion title="ブラウザバイナリが見つからない">
    Refrain は Chromium バイナリを自動的にバンドルします。見つからない場合は再インストールしてください：

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

    企業プロキシの配下にある場合は、Playwright の CDN からのダウンロードが許可されていることを確認してください。
  </Accordion>
</AccordionGroup>

## AI プロバイダー関連

<AccordionGroup>
  <Accordion title="「API キーが設定されていない」エラー">
    プロバイダーに対応する環境変数がエクスポートされていることを確認してください：

    ```bash theme={null}
    # Anthropic（デフォルト）
    export ANTHROPIC_API_KEY="sk-ant-..."

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

    全プロバイダーの変数は [AI プロバイダーを設定する](/ja/guides/ai-setup)を参照してください。
  </Accordion>

  <Accordion title="レート制限エラー（429）">
    プロバイダーのレート制限に達しました。対処法：

    * 待って再試行 — Refrain は指数バックオフで自動リトライします
    * 別のモデルやプロバイダーを使用
    * AI プロバイダーに制限の引き上げを依頼
  </Accordion>

  <Accordion title="モデル ID が見つからない">
    モデル ID がプロバイダーに一致しているか確認してください。主な例：

    * 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>

## 生成関連

<AccordionGroup>
  <Accordion title="AI が行き詰まる・同じ操作を繰り返す">
    * **Enter** キーで一時停止してガイダンスを入力
    * `context.md` に対象ページの詳細を追加
    * より具体的な `--goal` を指定
    * ワークフローが長い場合は `--max-iterations` を増加
  </Accordion>

  <Accordion title="AI が間違ったページを探索する">
    `context.md` にナビゲーションのヒントを追加してください：

    ```markdown theme={null}
    - ログイン後、ダッシュボードではなく直接 /settings に移動
    - エクスポートボタンは「ダッシュボード」タブではなく「レポート」タブの下にある
    ```
  </Accordion>

  <Accordion title="ゴールが達成されない">
    生成されたレポートで AI が停止した箇所を確認してください。一般的な原因：

    * コンテキスト不足 — `context.md` に詳細を追加
    * bot 検出 — `--stealth` モードを試す
    * 複雑なマルチステップワークフロー — 小さなゴールに分割
  </Accordion>

  <Accordion title="bot 検出でブラウザがブロックされる">
    ステルスモードで検出回避パッチを適用してください：

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

    一部のサイトでは `--proxy` でレジデンシャルプロキシを経由する必要がある場合もあります。
  </Accordion>
</AccordionGroup>

## 実行関連

<AccordionGroup>
  <Accordion title="セレクタ解決が失敗する">
    手順書生成後に UI が変更された可能性があります。対処法：

    1. `--self-heal` で AI 修正提案を取得
    2. `--headless false` でページの状態を目視確認
    3. `--screenshots` で各ステップのページ状態をキャプチャ
  </Accordion>

  <Accordion title="変数が解決されない">
    変数の `source` タイプを確認してください：

    * `prompt` — CLI で対話入力を求める
    * `env` — 環境変数から読み取り（エクスポートされているか確認）
    * `context` — `--context` ファイルが必要
    * `fixed` — 手順書定義内に値が必要
    * `secrets` — `--secrets` ファイルが必要
  </Accordion>

  <Accordion title="タイムアウトエラー">
    ページの読み込みが遅い可能性があります。対処法：

    * `--step-delay` を増やしてステップ間の待機時間を確保
    * 失敗ステップの前に `wait` ステップを追加
    * 対象サイトへのネットワーク接続を確認
  </Accordion>

  <Accordion title="ダウンロードファイルが見つからない">
    `--output-dir` が設定されていることを確認してください：

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

    ディレクトリは存在しない場合に自動作成されます。
  </Accordion>
</AccordionGroup>

## 承認・通知関連

<AccordionGroup>
  <Accordion title="Slack のボタンで「This didn't work」が表示される">
    Interactivity の Request URL が無効またはアクセスできない状態です。Slack App の Interactivity 設定を確認してください。詳細は[承認と通知](/ja/guides/approval-and-notifications)を参照してください。
  </Accordion>

  <Accordion title="承認がタイムアウトする">
    コールバックがエグゼキュータに到達していません。コールバックエンドポイントがインターネットからアクセス可能で、Request URL が正しく設定されているか確認してください。
  </Accordion>

  <Accordion title="'not_in_channel' エラー">
    ボットが Slack チャンネルに招待されていません。対象チャンネルで `/invite @your-bot-name` を実行してください。
  </Accordion>
</AccordionGroup>

## デバッグツール

トラブルシューティング時に役立つフラグ：

| フラグ                   | 機能                       |
| --------------------- | ------------------------ |
| `--headless false`    | ブラウザウィンドウを表示して何が起きているか確認 |
| `--screenshots <dir>` | 各ステップ後にスクリーンショットを保存      |
| `--report`            | 詳細な Markdown 実行レポートを生成   |
| `--debug`             | コンソールにデバッグ出力             |

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

## ヘルプ

* [CLI リファレンス](/ja/cli/overview) — 全コマンドとオプション
* [YAML リファレンス](/ja/yaml/overview) — 手順書スキーマドキュメント
* [プラン](/ja/concepts/plan-tiers) — プラン別の機能一覧