トラブルシューティング

"Service is experiencing high traffic. Please try again later!"

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

発生するタイミング:

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

回復手順（順番に）:

インストールとセットアップの問題

システム要件:

• 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" と表示されていること）

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

ログを確認する:

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

Verdent for VS Code にログインできない

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

解決策:

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

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

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

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

登録に失敗する

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

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

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

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

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

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

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

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

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

パフォーマンスの問題

症状:

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

よくある原因と対処:

画像関連のエラーメッセージ

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

file_edit の失敗

エラー: "Failed to find exact match"

原因:

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

解決策:

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

bash コマンドの失敗

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

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

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

# 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 で使用してください
• ファイル/ディレクトリの権限を確認する

検索で結果が返らない

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

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

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

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

除外設定を確認する:

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

大文字・小文字の区別:

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

サブエージェントが呼び出されない

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

チェックリスト:

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

手動でテストする:

@subagent-name perform task

組み込みサブエージェントの動作

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

よくある原因:

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

解決策:

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

AGENTS.md が適用されない

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

診断:

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

優先順位の確認:

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

MCP 接続の失敗

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

診断ステップ:

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

よくある対処:

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

バイナリファイルの制限

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

回避策:

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

大きなファイルの扱い

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

回避策:

# 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")

プラットフォーム間のコマンドの違い

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

回避策:

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

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

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