Skip to main content
リファレンス

トラブルシューティング

観察した症状やエラーメッセージから、原因と対処法を特定します。

このページは観察した症状から引けるように構成しています。すでにエラーコード、例外クラス名、プロセス終了コードが分かっている場合は、エラーの識別子から引けるエラーとエラーコードを参照してください。

セッションが起動しない

症状： query() が何も出力しない、または最初の await が長時間止まったあとに例外を投げる。
原因確認方法対処
qodercli 実行ファイルが PATH にない例外が QoderCliProcessError で、メッセージに実行ファイルが含まれるpathToQoderCLIExecutable を設定するか、QODERCLI_PATH をエクスポートする
起動が読み込みタイムアウトを超えた毎回一定時間後に失敗するloadTimeoutMs を上げる。ディスクが遅い環境のコールドスタートは既定値を超えることがある
認証情報が未設定例外に code: 'auth_not_configured' が付くauth を渡す。認証を参照
認証情報の環境変数が未設定code: 'auth_access_token_env_var_not_configured' または ..._service_account_...認証ヘルパーが読む変数をエクスポートする
起動時の問題を調べるときは stderr を取得してください。多くの場合、そこに実際の原因が示されています。 
options: {
  stderr: (data) => process.stderr.write(data),
}

プロセス起動前にオプションが拒否される

一部のオプションは事前に検証されるため、つづり間違いは即座に失敗し、機能が黙って無効化されることはありません。以下の例外は Qoder CLI の起動前に同期的に投げられます。
メッセージ原因対処
securityScan contains unknown option: <key>
security_scan contains unknown option: <key>.		スイッチ名のつづり間違いTypeScript は l1StaticCheck / l2LightweightScan / l3DeepScan、Python は l1_static_check / l2_lightweight_scan / l3_deep_scan
securityScan.<key> must be a boolean
security_scan.<key> must be a bool.		'yes' のような文字列を渡したtrue または false を渡す
security_scan must be a dict.Python 側で辞書以外の値を渡したスイッチをまとめた dict を渡す
native mode requires at least one enabled scope; use memory: {} to disable SDK memoryprojectScope と userScope を同時に false にした（TypeScript のみ）どちらか1つを残すか、memory: {} でメモリを無効にする
[createSdkMcpServer] Server name must be a non-empty string.name が未指定または空サーバーに名前を付ける
[createSdkMcpServer] Tool name must be a non-empty string in server "<server>".ツール定義に名前がないすべてのツールに名前を付ける
[createSdkMcpServer] Tool "<tool>" must have a non-empty description string.description がない説明を追加する。モデルはこれを見て呼び出すかを判断する

SDK とランタイムのバージョンが合わない

症状： ProtocolVersionMismatchError または UnsupportedCliCapabilityError。 SDK と Qoder CLI が互換性のないバージョンであることを意味します。通常は、パッケージ同梱のランタイムを使わず、ランタイムを個別に管理している場合に発生します。 
try {
  for await (const message of query({ prompt: 'ping' })) { /* ... */ }
} catch (error) {
  if (error instanceof UnsupportedCliCapabilityError) {
    console.error(`runtime lacks capability: ${error.capability}`);
  }
}
UnsupportedCliCapabilityError.capability に不足している機能が示されるため、ランタイムを更新すべきか、そのオプションの使用をやめるべきかを判断できます。Qoder CLI を更新するか、pathToQoderCLIExecutable の指定を外して同梱のランタイムを使ってください。

Agent がカスタムツールを呼び出さない

症状： ツールを登録しセッションも正常に起動するが、Agent はそのツールを使わずにタスクを終える。 次の順で確認してください。
  1. 完全修飾名を確認する。 サーバー名が my_tools、ツール名が greet の場合、モデルから見た名前は mcp__my_tools__greet です。許可リストには完全な名前を使う必要があります。
  2. 許可リストで除外されていないか確認する。 tools または allowedTools を設定していてそのツールを含めていない場合、モデルはそれを認識しません。MCPを参照してください。
  3. 遅延読み込みの影響を確認する。 MCP の遅延読み込みが有効な場合、すべてのツールが常駐するわけではありません。常に利用可能にすべきツールには印を付けます。
tool('greet', 'Say hello', { name: z.string() }, handler, { alwaysLoad: true })
  1. ツールの説明を確認する。 説明は、そのツールが適用される場面をモデルが判断する唯一の手がかりです。「何かをする」といった説明は無視されるため、発動条件を明記してください。

権限があるはずの操作で Agent が止まる

症状： ツール呼び出しが拒否される、または到達しない承認を待って処理が停滞する。
原因対処
disallowedTools がそのツールを含んでいるdisallowedTools は allowedTools や permissionMode より優先される
非対話ジョブに承認処理がない対話プロンプトを必要としない permissionMode を設定するか、canUseTool を渡す
canUseTool と permissionPromptToolName を同時に設定した両者は排他です。どちらか一方を選ぶ
優先順位の全体は権限制御を参照してください。

モデル選択のコールバックがタイムアウトする

症状： ModelPolicyTimeoutError。 resolveModel は毎リクエストのクリティカルパス上にあり、既定の予算は 500 ミリ秒です。コールバック内でデータベースへの問い合わせや HTTP 呼び出しを行うと、この予算を超えます。 
options: {
  resolveModel: async (context) => ({ model: pickModel(context) }), // ローカル処理に留める
  resolveModelTimeoutMs: 1_500,                                     // または予算を上げる
}
タイムアウトを繰り返し引き上げるのではなく、コールバックの外側で判断結果をキャッシュしてください。ここでの1ミリ秒は、毎ターンに積み上がります。

メモリが書き込まれない

TypeScript のみに該当します —— Python SDK に memory オプションはありません。 症状： Agent が新しい知識を得たが、実行終了後に何も保存されていない。 生成はターン完了後にバックグラウンド Agent が実行します。最終の result メッセージを受け取った直後にプロセスが終了すると、書き込み中の処理が中断される可能性があります。 
// 終了前に未完了の生成を待つ
await q.flushMemory();
flushMemory() が戻ってもファイルが変わらない場合は、生成結果を確認してください。no_change と skipped は正常な結果であり、失敗ではありません。メモリの実行結果を確認するを参照してください。

設定で有効にした機能が働かない

症状： 設定ファイルで有効にしているが、セッションでは無効のように振る舞う。 一部の Query オプションは優先度が最も高く、渡された時点で対応する設定ブロックをマージではなく置き換えます。明示的に指定されていないスイッチはすべて false として扱われます。 securityScan がこれに該当します。settings.json で l1StaticCheck を有効にしていても、Query が securityScan: { l3DeepScan: true } を渡すと、そのセッションの l1StaticCheck は無効になります。有効に保ちたいスイッチはすべて再指定してください。このオプションは設定を上書きし、マージしないを参照してください。

設定していないルールに Agent が従う

症状： プロンプトに存在しない規約に Agent が従っている。 Qoder CLI を実行するマシン上の指示ファイルは既定で読み込まれ、それらは他のファイルを取り込むこともできます。実際に何が読み込まれたかをログで確認してください。 
options: {
  hooks: {
    InstructionsLoaded: [{ hooks: [async (input) => {
      console.log(input.memory_type, input.file_path, input.load_reason);
      return {};
    }] }],
  },
}
ホスト間で再現可能な実行結果が必要な場合は、settingSources: [] でディスクから何も読み込まないようにします。ファイルシステムから指示を読み込むを参照してください。

報告に使える診断情報を収集する

エスカレーションが必要な場合は、状態が失われる前に次の情報を収集してください。 
options: {
  debug: true,
  debugFile: '/tmp/qoder-sdk-debug.ndjson',
  stderr: (data) => process.stderr.write(data),
}
併せて、SDK のバージョン、system/init メッセージ内の Qoder CLI のバージョン、session_id、Result の subtype と存在する場合の error_code を記録してください。診断上明確に必要な場合を除き、認証情報、プロンプト、ソースコードの内容はマスクしてください。ログとサポートを参照してください。

次のステップ

クイックスタート
基本概念
会話とセッション
ツールと拡張機能
制御と安全性
リファレンス
トラブルシューティング - Qoder