エラーの処理とリカバリー

エラーを解釈し、対応し、報告する方法を理解することで、Verdent for VS Code を使った開発セッションを生産的に進められます。

このページで学べること

よくあるエラーの種類とその原因
エラーメッセージを効果的に解釈する方法
体系的なトラブルシューティングの手順
待つべき場合と行動すべき場合の判断
Verdent チームへの問題報告方法

よくあるエラーの種類

包括的なエラードキュメントは現在作成中です。以下の情報は、最も頻繁に遭遇するエラーカテゴリーを扱っています。特定のエラーシナリオについては、support@verdent.ai に連絡するか、Discord コミュニティをご利用ください。

サーバー過負荷エラー

トラフィックが多い時間帯に発生
一時的な容量制約
対処: 5〜10 分待ってから再試行する

内部サーバーエラー

バックエンドの処理に関する問題
一時的なサービス障害
対処: 待ってから再試行する。通常は自動的に解決します

503 Service Unavailable

正常な上流サーバーが存在しない
一時的なインフラの問題
対処: サービスの復旧を待つ

レート制限エラー

リクエスト割り当てを超過
API のスロットリング保護
対処: レート制限のリセットを待ち、リクエスト頻度を減らす

無効または期限切れの認証情報
セッションタイムアウトの問題
対処: User Center から再認証し、サブスクリプションが有効か確認する

ネットワーク接続の問題
ファイアウォールまたは VPN による接続のブロック
企業ネットワークの制限
対処: ネットワーク接続を確認し、別のネットワークを試す

無効な設定または環境設定
破損した設定ファイル
対処: 最近の設定変更を見直し、設定を確認する

ファイルシステムの権限不足
ワークスペースへのアクセス制限
対処: ファイル/フォルダーの権限を確認し、ワークスペースへのアクセスを確認する

エラーメッセージの解釈

詳細なエラーメッセージ解釈ガイドは現在開発中です。遭遇した特定のエラーメッセージについては、Feedback ボタンまたは Discord コミュニティをご利用ください。

サーバー側エラーは一時的なもので、通常は待つだけで解決します。数分後に再試行する以外の対応は不要です。

次のキーワードに注目してください:

"Overloaded" または "at capacity"
"Internal server error" または "backend processing"
"503 Service Unavailable" または "no healthy upstream"
"Rate limit" または "quota"

やるべきこと:

再試行する前に 5〜10 分待つ
ローカルでの開発作業を続ける
これまでに行ったコード変更を見直す
現在の作業を Git にコミットする

一般的なルール: エラーメッセージにサーバーの状態、容量、またはレート制限が記載されている場合、それは一時的なものです。これらは自動的に解決するインフラの問題です。

一時的なサーバーエラー（502、503、504）は通常、数分以内に解決します。再試行する前に 2〜3 分待ってください。

エスカレートすべき場合:

エラーが 15 分以上続く
Discord で障害報告を確認する
ステータスページの更新を確認する

クライアント側エラーには、あなた自身の対応が必要です。これらは待っても解決しません。

次の兆候に注目してください:

認証や認証情報に関連するメッセージ
設定や構成のエラー
ファイル権限のエラー
ネットワーク接続の失敗

やるべきこと:

認証エラー: User Center から再認証し、サブスクリプションが有効か確認する
設定エラー: 最近の設定変更を見直し、設定ファイルを確認する
権限エラー: ファイル/フォルダーの権限を確認し、ワークスペースへのアクセスを確認する
ネットワークエラー: インターネット接続をテストし、別のネットワークを試し、VPN/ファイアウォールを確認する

一般的なルール: エラーに認証、設定、権限、またはローカル設定が記載されている場合、修正のための対応が必要です。

トラブルシューティングの手順:

エラーメッセージ全文を読んで具体的な指示を確認する
どのコンポーネントがエラーを報告したかを特定する（認証、設定、権限、ネットワーク）
エラーの種類に応じて的を絞った対応をとる
元の操作を再試行して修正を確認する

エラーのコンテキストを読み取る

エラーが発生したとき:

エラーメッセージを最後まで読む - 詳細を飛ばさない
エラーコードに注目する - 特定のコードが問題の診断に役立つ
コンポーネントを特定する - どのシステムがエラーを報告したか（サーバー、API、ローカル）
タイミングを確認する - すぐに発生したか、遅れて発生したか？

体系的なトラブルシューティング

Verdent が予期しない動作をした場合は、最も影響の少ない操作から順に、以下の手順に従ってください。

最初の対応

待って観察する

動作が一貫しているか断続的かを確認します。どの操作が予期しない動作を引き起こしたかを記録します。すぐに何かが壊れていると決めつけないでください。多くの問題は一時的なものです。

基本的な再起動

Verdent for VS Code を再起動します（VS Code を閉じて再度開く）。スタックした状態やパフォーマンスの問題が解決することが多いです。これは最もシンプルな最初のトラブルシューティング手順です。

段階的なトラブルシューティング

基本的な再起動で問題が解決しない場合:

体系的なトラブルシューティング手順を順番に実行してください。手順を飛ばすと、根本原因を見逃すことが多くあります。

ネットワーク接続を確認する

他のウェブサイトでインターネット接続をテストします。別のネットワーク（モバイルホットスポット）で試し、ファイアウォール/VPN の問題を除外します。企業ネットワークが接続をブロックしていないか確認します。

設定を確認する

まだ認証されているか確認します。User Center でサブスクリプションが有効か確認します。動作に影響を与える可能性のある最近の設定変更を見直します。

サポートを求める

Discord コミュニティで同様の報告を確認します: https://discord.com/invite/NGjXEZcbJq。Feedback ボタンを使って問題を報告します。予期しない動作の説明と再現手順を含めてください。

やってはいけないこと

一時的な問題に対しては、以下の操作を避けてください:

すぐに Verdent を再インストールしない
VS Code のキャッシュやアプリケーションデータを消去しない
一時的な問題のためにシステム設定を変更しない
他のアプリケーションも影響を受けていない限り、コンピューターを再起動しない

Manual Accept Mode では、正確なコマンドを慎重に確認せずに破壊的な操作（rm、DROP、DELETE）を承認しないでください。

なぜ？ これらの操作は時間がかかり、問題を解決することはめったにありません。ほとんどの問題は、シンプルな再起動や一時的なサーバー問題の解消を待つことで解決します。

待つべき場合と行動すべき場合

待つべきか行動すべきかを理解することで、無駄なトラブルシューティングを防げます。

これらのエラーは自動的に解決します。待って再試行する以外の対応は不要です。

サーバー過負荷または容量エラー:

"Overloaded" または "at capacity" のメッセージ
トラフィックが多い時間帯
一時的なサービス障害

レート制限:

"Rate limit" または "quota exceeded" のメッセージ
短時間に多すぎるリクエスト
API のスロットリング保護

断続的な接続の問題:

時々失敗するが再試行で成功するリクエスト
ネットワークの一時的な不調
一瞬の接続断

待っている間にやるべきこと:

ローカルでの開発作業を続ける
これまでに行ったコード変更を見直す
次のステップや TODO を計画する
現在の作業を Git にコミットする

待つ時間の目安:

標準的な待機時間: 5〜10 分
10 分後もまだ失敗する場合は、トラブルシューティングに切り替える
広範囲な問題の報告がないか Discord を確認する

これらのエラーは待っても解決しません。修正のための対応が必要です。

認証の失敗:

セッションの期限切れ → User Center から再認証する
無効な認証情報 → サブスクリプションが有効か確認する
再認証が必要 → User Center を確認する

持続的なエラー（10 分以上）:

複数回の再試行後も同じエラーが繰り返される → トラブルシューティングを開始する
一貫した失敗パターン → 設定を確認する
再起動しても続くエラー → 環境を確認する

設定の問題:

最近設定を変更した → 変更を見直して元に戻す
新規セットアップまたはインストール → 設定ファイルを確認する
ネットワーク環境を変更した → 接続をテストする

権限エラー:

ファイルシステムへのアクセスが拒否された → ファイル/フォルダーの権限を確認する
ワークスペースの制限 → ワークスペースへのアクセスを確認する
フォルダーの権限 → 必要な権限を付与する

ネットワークの問題:

まったく接続できない → インターネット接続をテストする
VPN またはファイアウォールによるブロック → 別のネットワークを試す
企業ネットワークの制限 → IT サポートに連絡する

判断ルール:

サーバー/レートのエラー → 待つ
認証/設定/権限/ネットワーク → すぐに行動する
判断がつかない場合 → まず 5〜10 分待ち、続くようなら行動する

エラーのコンテキストを提供する

サポートを求めたり問題を報告したりする際は、迅速な診断のために包括的なコンテキストを含めてください。

必須の情報

エラーの詳細:

正確なエラーメッセージの本文（コピー＆ペーストし、言い換えない）
提供されている場合はエラーコード
エラーが発生したタイムスタンプ
頻度（一度きり、断続的、一貫している）

環境:

Verdent for VS Code のバージョン
VS Code のバージョン
オペレーティングシステムとそのバージョン
ネットワーク環境（自宅、企業、VPN）

再現手順:

何をしようとしていたか
使用した正確なプロンプトまたはコマンド
関係するファイルやコンテキスト
エラー前に行った操作

コンテキスト:

使用していた実行モード
ワークスペースのサイズと複雑さ
最近の設定変更
過去に成功した同様の操作

エラー報告の例

良いエラー報告のフォーマット:

Issue: Getting "Internal server error" when requesting code analysis

Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."

Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)

Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request

Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally

これが効果的な理由

正確なエラーメッセージの本文
完全な環境の詳細
明確な再現手順
正常に動作するシナリオとの比較
パターンに関する追加のコンテキスト

問題の報告

場所: Verdent パネルの上部バー

機能:

問題や提案を送信するためのポップアップオーバーレイを開く
Verdent チームへの直接の連絡チャネル
バグ報告や機能リクエストに最適

使用する場面:

明確な再現手順がある確認済みのバグ
具体的なユースケースを伴う機能リクエスト
チームとの直接のやり取りが必要な場合
調査が必要な緊急ではない問題

含めるべき内容:

問題の明確な説明
エラーメッセージ（正確な本文）
再現手順
期待される動作と実際の動作
Verdent のバージョンとプラットフォーム
問題が始まった時期

リンク: https://discord.com/invite/NGjXEZcbJq

提供される内容:

Verdent のユーザーとチームメンバーが集まる活発なコミュニティ
リアルタイムのトラブルシューティング支援
スクリーンショット付きで問題を共有
経験豊富なユーザーからのサポート
コミュニティでの議論や回避策

使用する場面:

即座の議論が必要な緊急の問題
やり取りが必要な複雑なトラブルシューティング
ベストプラクティスに関するコミュニティの意見
正式な報告を提出する前の簡単な質問
コミュニティとの回避策の共有

問題の種類	Feedback ボタンを使う	Discord を使う
再現手順がある確認済みのバグ	✓
機能リクエスト	✓
緊急のトラブルシューティングが必要		✓
議論が必要な複雑な問題		✓
簡単な質問		✓
コミュニティの意見が欲しい		✓
正式なバグ報告	✓
一般的なサポート		✓

報告すべきでないこと:

一時的なサーバーエラー（10 分未満）
トラフィックが多い時間帯
すでに文書化されている問題
期待される動作

代わりに: 一時的な問題は待ち、最近の報告を Discord で確認し、ドキュメントを見直してください。

予防のベストプラクティス

事前の対策により、エラーの発生頻度を減らし、エラー発生時のリカバリーを改善できます。

プロンプトに具体的な表現を使い、関連するファイルのコンテキストを含めることで、よくあるエラーの多くを未然に防げます。

作業を始める前に

1. セットアップを確認する

User Center で認証状態を確認する
サブスクリプションが有効か確認する
安定したネットワーク接続を確保する
最近の設定変更を見直す

2. Git を初期化する

許可的なモードを使う前に、常にバージョン管理を用意する
きれいな開始地点にするため現在の作業をコミットする
問題が発生した場合のロールバックの選択肢を確保する

3. クレジット残高を確認する

計画している作業に十分なクレジットがあるか確認する
複雑なタスクを始める前に、必要に応じてチャージする
クレジット不足によるタスク途中の中断を避ける

開発中

1. 適切な実行モードを使う

馴染みのないコードには Manual Accept
複雑な変更には Plan Mode
Auto-Run は Git のセーフティネットがある場合のみ
リスクレベルに応じてモードを選ぶ

2. パフォーマンスを監視する

応答品質の低下に注意する
応答時間が遅くなっていないか確認する
パフォーマンスが低下したら新しいセッションを開始する
コンテキストの使用量を手動で追跡する

3. 明確で具体的なプロンプト

誤解されたリクエストによるエラーを減らす
関連するコンテキストと制約を含める
既存のパターンを参照する
スコープを明確に指定する

エラー発生後

1. パターンから学ぶ

何がエラーを引き起こしたかを記録する
再現可能な条件を特定する
トリガーを避けるようにワークフローを調整する
発見した内容をコミュニティと共有する

2. 回避策を文書化する

効果的な解決策をメモしておく
チームメンバーと共有する
コミュニティの知識に貢献する
修正のために Verdent チームに報告する

3. 設定を更新する

経験に基づいて設定を調整する
自分のワークフローに合わせて最適化する
問題を防ぐためにルールを設定する
AGENTS.md のドキュメントを維持する