# トラブルシューティング (/ja/docs/verdent-for-vscode/help-support/common-issues)

> よくある問題、診断、解決策



### このページで学べること [#このページで学べること]

Verdent for VS Code の一般的なトラブルシューティング手順、診断ステップ、既知の問題の回避策を紹介します。

<Info>
  ユーザーから報告の多い問題への詳細なトラブルシューティングは、サポートデータをもとに現在整備中です。このページでは一般的な診断手順を扱います。ここで扱っていない個別の問題については [support@verdent.ai](mailto:support@verdent.ai) までお問い合わせください。
</Info>

***

## クイック診断 [#クイック診断]

<Tabs>
  <Tab title="サービスエラー（最も多い）">
    ### "Service is experiencing high traffic. Please try again later!" [#service-is-experiencing-high-traffic-please-try-again-later]

    **これはユーザーが遭遇する最も多いエラーです。** Verdent のサービスが一時的に過負荷になっていることを示しています。

    **発生するタイミング:**

    * 利用がピークになる時間帯
    * バックエンドサービスに高い負荷がかかっているとき
    * 一時的なサービス品質の低下

    **回復手順（順番に）:**

    <Steps>
      <Step title="メッセージをロールバックする" stepNumber="1">
        エラーが続く場合は、直近のメッセージをロールバックします。

        * チャット画面でロールバック/取り消しボタンを選択します
        * 少し待ってからリクエストを再送信します
      </Step>

      <Step title="新しいセッションを開始する" stepNumber="2">
        それでもエラーが続く場合は、新しいセッションを開始します。

        * トップバーの「+」（新しいセッション）ボタンを選択します
        * これによりコンテキストとツールの承認がクリアされます
        * クリーンなセッションでリクエストを再送信します
      </Step>

      <Step title="待ってから再試行する" stepNumber="3">
        30〜60秒待ってから、もう一度リクエストを試します。ほとんどのサービス問題はすぐに解消します。
      </Step>
    </Steps>

    <Warning>
      複数のセッションをまたいで5〜10分以上問題が続く場合は、[Verdent のステータスページ](https://verdent.ai/status) を確認するか、[support@verdent.ai](mailto:support@verdent.ai) までお問い合わせください。
    </Warning>
  </Tab>

  <Tab title="インストールとセットアップ">
    ### インストールとセットアップの問題 [#インストールとセットアップの問題]

    **システム要件:**

    * **VS Code のバージョン:** 1.90.0 以降（必須）
    * **インターネット接続:** 有効な接続が必要
    * **サブスクリプション:** 有効な Verdent サブスクリプション

    **基本的な診断チェックリスト:**

    1. **VS Code のバージョンを確認:** Help → About（1.90.0 以降であること）
    2. **インターネット接続を確認:** Verdent には有効な接続が必要です
    3. **サブスクリプションを確認:** Verdent サブスクリプションが有効であることを確認します
    4. **VS Code を再起動:** インストールや設定の変更後に行います
    5. **拡張機能の状態を確認:** View → Extensions → Verdent（"Enabled" と表示されていること）

    **クリーン再インストール手順:**

    <Steps>
      <Step title="Verdent をアンインストールする">
        View → Extensions → Verdent → Uninstall
      </Step>

      <Step title="VS Code を再起動する">
        VS Code を完全に閉じてから再度開きます
      </Step>

      <Step title="Verdent を再インストールする">
        View → Extensions → "Verdent" を検索 → Install
      </Step>
    </Steps>

    **ログを確認する:**

    * 出力パネルを開く: View → Output
    * ドロップダウンから "Verdent" を選択します
    * エラーメッセージやスタックトレースを確認します

    <Info>
      インストールの問題のほとんどは、VS Code の再読み込みまたはクリーン再インストールで解決します。問題が続く場合は、ログを確認し、ログの詳細を添えてサポートにお問い合わせください。
    </Info>
  </Tab>

  <Tab title="認証とアカウント">
    ### Verdent for VS Code にログインできない [#verdent-for-vs-code-にログインできない]

    **最も多い原因:** プロキシ設定の問題

    **解決策:**

    <Steps>
      <Step title="VS Code の設定を開く">
        `Cmd+,`（macOS）または `Ctrl+,`（Windows/Linux）を押します
      </Step>

      <Step title="プロキシ設定を検索する">
        設定の検索バーで "useProxy" または "verdent.enableProxy" を検索します
      </Step>

      <Step title="プロキシの状態を切り替える">
        プロキシ設定をオン/オフ（現在と逆の状態）に切り替えます
      </Step>

      <Step title="再度ログインする">
        もう一度 Verdent へのログインを試します
      </Step>
    </Steps>

    <Info>
      企業のファイアウォール内にいる場合は、プロキシ設定を有効にする必要があるかもしれません。家庭のネットワークを使用している場合は、無効にしてみてください。
    </Info>

    ***

    ### 無料トライアルのクレジットが付与されない [#無料トライアルのクレジットが付与されない]

    **エラー:** 無料トライアルのクレジットが付与されない、または無料トライアルへのアクセスが拒否される

    **理由:** 登録時に利用規約違反が検出された

    **解決策:** 無料トライアルへのアクセスについては [support@verdent.ai](mailto:support@verdent.ai) までお問い合わせください。サポートチームがアカウントを確認し、問題の解決をお手伝いします。

    ***

    ### 登録に失敗する [#登録に失敗する]

    **エラー:** アカウント登録が拒否された、または制限された

    **理由:** 登録が Verdent の利用規約に違反したため、アクセスが制限されました

    **解決策:** [support@verdent.ai](mailto:support@verdent.ai) までお問い合わせください。サポートチームが登録内容を確認し、問題解決の方法をご案内します。

    ***

    ### モデルが表示されない（Claude、GPT、Gemini） [#モデルが表示されないclaudegptgemini]

    **問題:** モデル選択画面で Claude、GPT、Gemini のモデルが見つからない

    **理由:** モデルプロバイダーによる地域ベースの制限

    **説明:** 一部の AI モデルプロバイダーには地域制限があり、特定の地理的な場所では一部のモデルが利用できません。この場合:

    * 制限されたモデルはモデル選択メニューに表示されません
    * その他の利用可能なモデルは引き続き問題なく使用できます
    * サブスクリプションやクレジットには影響しません

    **利用可能なモデルを確認する:** [https://www.verdent.ai/regions](https://www.verdent.ai/regions) にアクセスして、お住まいの地域で利用可能なモデルを確認してください

    <Note>
      地域制限は AI モデルプロバイダー（Anthropic、OpenAI、Google）によって設定されており、Verdent によるものではありません。Verdent はこれらの制限を上書きできません。
    </Note>
  </Tab>

  <Tab title="パフォーマンス">
    ### パフォーマンスの問題 [#パフォーマンスの問題]

    **症状:**

    * 応答が遅い
    * コンテキストウィンドウが満杯になるエラー
    * ツール実行のタイムアウト

    **よくある原因と対処:**

    | 問題         | 原因                 | 解決策                                                            |
    | ---------- | ------------------ | -------------------------------------------------------------- |
    | 応答が遅い      | 大きなファイルを読み込んでいる    | 行範囲を指定する: `file_read("file.js", start_line=100, max_lines=50)` |
    | コンテキストが満杯  | 会話履歴が長い            | サブエージェントに委任するか、新しい会話を開始する                                      |
    | ツールのタイムアウト | 長時間実行される bash コマンド | 明示的なタイムアウトを設定するか、より小さなコマンドに分割する                                |
    | メモリ使用量が多い  | 並列処理が多すぎる          | 同時実行するツールの数を制限する                                               |

    <Tip>
      探索的なタスクは @Explorer サブエージェントに委任し、メイン側のコンテキストを温存しましょう。
    </Tip>
  </Tab>

  <Tab title="画像エラー">
    ### 画像関連のエラーメッセージ [#画像関連のエラーメッセージ]

    **よくある画像処理エラーのクイックリファレンス:**

    | エラーメッセージ                       | 原因                                               | 解決策                                |
    | ------------------------------ | ------------------------------------------------ | ---------------------------------- |
    | **Unsupported Image Type**     | JPEG、PNG、GIF、WebP の画像のみがサポートされています               | ロールバックして、画像をサポートされている形式に変更します      |
    | **Image Dimensions Too Large** | 画像の幅または高さは 8000 ピクセルを超えられません                     | ロールバックして、画像サイズを 8000×8000 以下に調整します |
    | **Input Too Long**             | 入力がモデルの最大許容長を超えています                              | 入力を簡略化するか、画像サイズを小さくします             |
    | **File Too Large**             | 画像サイズは 5 MB を超えられません                             | ロールバックして、圧縮した画像（最大 5 MB）を送信します     |
    | **Unreadable Image**           | 画像を処理できませんでした。ファイルが破損しているか、サポートされていない形式の可能性があります | ロールバックして、有効なファイルに画像を差し替えます         |
  </Tab>
</Tabs>

***

## ツール固有の問題 [#ツール固有の問題]

<Tabs>
  <Tab title="file_edit の失敗">
    ### file\_edit の失敗 [#file_edit-の失敗]

    **エラー:** "Failed to find exact match"

    **原因:**

    * 前回の file\_read 以降にテキストが変更された
    * 空白の違い（タブとスペース）
    * 文字列がファイル内で一意でない

    **解決策:**

    ```bash
    # 1. Read file again to get current state
    file_read("file.js")

    # 2. Use larger context string for uniqueness
    file_edit("file.js",
      old_string="function foo() {\n  return 42;\n}",
      new_string="...")

    # 3. For multiple identical strings, use replace_all
    file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)
    ```

    <Warning>
      編集の直前に必ずファイルを読み込み、最新の状態を把握してから編集してください。
    </Warning>
  </Tab>

  <Tab title="bash の失敗">
    ### bash コマンドの失敗 [#bash-コマンドの失敗]

    **エラー:** コマンドのタイムアウトまたは実行失敗

    **最大タイムアウト:** 120秒（2分、ハードリミット）

    **解決策:** 長いコマンドをより小さな操作に分割します:

    ```bash
    # Instead of one long command, break into steps
    bash("step1")  # Completes in < 2min
    bash("step2")  # Completes in < 2min
    ```

    **コマンドが見つからない:**

    * コマンドが存在するか確認する: `bash("which command-name")`
    * 正しいパスを確認するか、先に環境を有効化する
    * 実行ファイルにはフルパスを使用する

    **権限エラー:**

    * コマンドはユーザー権限で実行されます
    * `sudo` は必要な場合に限り、かつ Manual Accept Mode で使用してください
    * ファイル/ディレクトリの権限を確認する
  </Tab>

  <Tab title="検索の問題">
    ### 検索で結果が返らない [#検索で結果が返らない]

    **問題:** grep\_file または glob が期待したファイルを見つけられない

    **パターンの構文を確認する:**

    ```bash
    # Wrong
    grep_file("*.ts")  # Missing ** for recursive

    # Correct
    grep_file("**/*.ts")  # Recursive search
    ```

    **除外設定を確認する:**

    ```bash
    # Ensure not accidentally excluding target files
    glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])
    ```

    **大文字・小文字の区別:**

    ```bash
    # Use case-insensitive search if needed
    grep_content("pattern", case_insensitive=true)
    ```
  </Tab>
</Tabs>

***

## サブエージェントと設定の問題 [#サブエージェントと設定の問題]

<Tabs>
  <Tab title="サブエージェントが呼び出されない">
    ### サブエージェントが呼び出されない [#サブエージェントが呼び出されない]

    **問題:** カスタムサブエージェントが自動的に起動しない

    **チェックリスト:**

    * ファイルの場所: `~/.verdent/subagents/[name].md`
    * `name` と `description` を含む有効な YAML フロントマター
    * 呼び出しポリシーが使い方と一致している（strict では @メンションが必要）
    * "When to use" のガイドラインがリクエストのパターンと一致している
    * markdown ファイルに構文エラーがない

    **手動でテストする:**

    ```
    @subagent-name perform task
    ```

    <Tip>
      自動呼び出しのトラブルシューティングを行う前に、明示的な @メンションでサブエージェントが動作することを確認しましょう。
    </Tip>
  </Tab>

  <Tab title="組み込みサブエージェント">
    ### 組み込みサブエージェントの動作 [#組み込みサブエージェントの動作]

    **問題:** @Explorer、@Verifier、@Code-reviewer が期待どおりに動作しない

    **よくある原因:**

    * リクエストがサブエージェントの専門分野と一致していない
    * サブエージェントのコンテキストが満杯（まれ）
    * メイン会話のコンテキストがルーティングに影響している

    **解決策:**

    * 明示的な @メンションを使って特定のサブエージェントを強制的に呼び出す
    * リクエストをサブエージェントの専門分野に合うよう言い換える
    * コンテキストが問題なら新しい会話を開始する
  </Tab>

  <Tab title="AGENTS.md のルール">
    ### AGENTS.md が適用されない [#agentsmd-が適用されない]

    **問題:** プロジェクトのルールが Verdent の動作に反映されない

    **診断:**

    1. **場所:** ファイルはプロジェクトのルートディレクトリに置く必要があります
    2. **構文:** 有効な Markdown（構文エラーがないか確認）
    3. **具体性:** ルールは指示的であること。「Try to use X」ではなく「Always use X」
    4. **テスト:** 新しい会話を開始して、最新の状態で適用をテストします

    **優先順位の確認:**

    ```markdown
    # In AGENTS.md (highest priority)
    - Use 4-space indentation

    # In VERDENT.md (lower priority)
    - Use 2-space indentation

    # Result: 4-space indentation (AGENTS.md wins)
    ```
  </Tab>

  <Tab title="MCP 接続">
    ### MCP 接続の失敗 [#mcp-接続の失敗]

    **エラー:** MCP サーバーに接続できない

    **診断ステップ:**

    1. **mcp.json を確認:** `~/.verdent/mcp.json` の JSON 構文が有効であること
    2. **サーバーが稼働中:** MCP サーバーのプロセスが動作していることを確認する
    3. **ネットワーク:** サーバーエンドポイントへの接続性を確認する
    4. **認証:** 認証情報が正しいことを確認する
    5. **ログ:** MCP サーバーのログでエラーの詳細を確認する

    **よくある対処:**

    * MCP サーバーを再起動する
    * 接続文字列の形式を確認する
    * MCP のトラフィックを許可するファイアウォールルールを確認する
    * API のキーやトークンを検証する
  </Tab>
</Tabs>

***

## 既知の問題と回避策 [#既知の問題と回避策]

<Tabs>
  <Tab title="バイナリファイル">
    ### バイナリファイルの制限 [#バイナリファイルの制限]

    **問題:** 画像、PDF、コンパイル済みバイナリを編集できない

    **回避策:**

    ```bash
    # Use bash to call external tools
    bash("convert input.png -resize 50% output.png")
    bash("pdftotext document.pdf output.txt")
    ```

    <Info>
      バイナリファイルの変更には、bash コマンド経由で呼び出す外部ツールが必要です。
    </Info>
  </Tab>

  <Tab title="大きなファイル">
    ### 大きなファイルの扱い [#大きなファイルの扱い]

    **問題:** 10,000行を超えるファイルはコンテキストの問題を引き起こす

    **回避策:**

    ```bash
    # Always use line ranges for large files
    file_read("large.log", start_line=1000, max_lines=100)

    # Search first to find relevant sections
    grep_content("ERROR", glob="large.log")
    ```

    <Tip>
      まず grep\_content で検索して関連する行番号を特定し、その特定の範囲だけを読み込みましょう。
    </Tip>
  </Tab>

  <Tab title="プラットフォームの違い">
    ### プラットフォーム間のコマンドの違い [#プラットフォーム間のコマンドの違い]

    **問題:** bash コマンドが Windows と Unix で異なる

    **回避策:**

    ```bash
    # Use cross-platform tools when possible
    bash("npm run build")  # Works everywhere

    # Or conditional execution
    bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
    ```

    **ベストプラクティス:** クロスプラットフォーム互換性のために npm スクリプトを使用しましょう。
  </Tab>
</Tabs>

***

## さらにサポートを受けるには [#さらにサポートを受けるには]

### サポート窓口 [#サポート窓口]

**ここで扱っていない個別の問題について:**

* **メール:** [support@verdent.ai](mailto:support@verdent.ai)
* **Discord:** [Verdent コミュニティに参加](https://discord.com/invite/NGjXEZcbJq) してリアルタイムのサポートを受けられます
* **GitHub Issues:** バグの報告や機能のリクエスト

**問題を報告する際は、以下を含めてください:**

1. Verdent のバージョン（拡張機能パネルから）
2. VS Code のバージョン
3. オペレーティングシステム
4. エラーメッセージ（正確なテキスト）
5. 再現手順
6. 期待される動作と実際の動作

***

### 診断情報の収集 [#診断情報の収集]

**サポートによる診断を助けるために:**

```bash
# VS Code version
bash("code --version")

# System info
bash("uname -a")  # Unix
bash("systeminfo")  # Windows

# Verdent logs location
# Check VS Code Output panel → Verdent
```

***

## 関連項目 [#関連項目]

<CardGroup cols="2">
  <Card title="よくある質問" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    よくある質問
  </Card>

  <Card title="制限事項" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    既知の制限事項と制約
  </Card>
</CardGroup>