Skip to Content
ユーザーガイドサポートトラブルシューティング

トラブルシューティング

このガイドでは、以下のような一般的な問題とデバッグのヒントに対する解決策を提供します。

  • 認証またはログインエラー
  • よくある質問 (FAQ)
  • デバッグのヒント
  • 既存の GitHub Issues の確認や新しい Issue の作成

認証またはログインエラー

  • エラー: UNABLE_TO_GET_ISSUER_CERT_LOCALLY、UNABLE_TO_VERIFY_LEAF_SIGNATURE、または unable to get local issuer certificate

    • 原因: SSL/TLS トラフィックを傍受して検査するファイアウォールを持つ企業ネットワーク上にいる可能性があります。これには、Node.js が信頼するカスタムルート CA 証明書が必要な場合があります。
    • 解決策: NODE_EXTRA_CA_CERTS 環境変数を企業のルート CA 証明書ファイルへの絶対パスに設定します。
      • 例: export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

  • エラー: Device authorization flow failed: fetch failed

    • 原因: Node.js が Qwen OAuth エンドポイントに到達できませんでした（プロキシまたは SSL/TLS 信頼の問題がよくあります）。利用可能な場合は、Qwen Code は根本的なエラー原因も出力します（例: UNABLE_TO_VERIFY_LEAF_SIGNATURE）。
    • 解決策:
      • 同じマシン/ネットワークから https://chat.qwen.ai にアクセスできることを確認してください。
      • プロキシの背後にある場合は、qwen --proxy <url>（または settings.json の proxy 設定）で設定してください。
      • ネットワークが企業の TLS 検査 CA を使用している場合は、上記のように NODE_EXTRA_CA_CERTS を設定してください。

  • 問題: 認証失敗後に UI が表示されない

    • 原因: 認証タイプを選択した後に認証が失敗した場合、security.auth.selectedType 設定が settings.json に保持されている可能性があります。再起動時に、CLI は失敗した認証タイプでの認証を試み続け、UI の表示に失敗することがあります。
    • 解決策: settings.json ファイル内の security.auth.selectedType 設定項目をクリアしてください:
      • ~/.qwen/settings.json を開く（プロジェクト固有の設定の場合は ./.qwen/settings.json）
      • security.auth.selectedType フィールドを削除する
      • CLI を再起動して、再度認証のプロンプトが表示されるようにする

よくある質問 (FAQ)

  • Q: Qwen Code を最新バージョンに更新するにはどうすればよいですか？

    • A: npm 経由でグローバルにインストールした場合は、コマンド npm install -g @qwen-code/qwen-code@latest を使用して更新してください。ソースからコンパイルした場合は、リポジトリから最新の変更をプルし、その後 npm run build コマンドを使用して再ビルドしてください。

  • Q: Qwen Code の設定ファイルや構成ファイルはどこに保存されていますか？

    • A: Qwen Code の構成は、2つの settings.json ファイルに保存されます：

      1. ホームディレクトリ内：~/.qwen/settings.json
      2. プロジェクトのルートディレクトリ内：./.qwen/settings.json

      詳細については、Qwen Code 構成 を参照してください。

  • Q: 統計出力にキャッシュされたトークン数が表示されないのはなぜですか？

    • A: キャッシュされたトークン情報は、キャッシュされたトークンが実際に使用されている場合にのみ表示されます。この機能は API キー利用者（Qwen API キーまたは Google Cloud Vertex AI）には利用可能ですが、OAuth 利用者（Google Gmail や Google Workspace などの Google 個人/エンタープライズアカウント）には利用できません。これは、Qwen Code Assist API がキャッシュされたコンテンツ作成をサポートしていないためです。/stats コマンドを使用して、引き続き総トークン使用量を確認できます。

よくあるエラーメッセージと解決策

  • エラー: MCPサーバー起動時に EADDRINUSE (Address already in use) が発生する。

    • 原因: 別のプロセスがMCPサーバーがバインドしようとしているポートを使用中です。
    • 解決策: ポートを使用中の他のプロセスを停止するか、MCPサーバーが別のポートを使用するように設定してください。

  • エラー: qwen コマンドで Qwen Code を実行しようとすると「コマンドが見つかりません」と表示される。

    • 原因: CLIが正しくインストールされていないか、システムの PATH に含まれていません。
    • 解決策: Qwen Code のインストール方法によって対応が異なります:
      • qwen をグローバルにインストールした場合、npm のグローバルバイナリディレクトリが PATH にあることを確認してください。更新には npm install -g @qwen-code/qwen-code@latest コマンドを使用します。
      • ソースから qwen を実行している場合は、正しいコマンドで呼び出していることを確認してください（例: node packages/cli/dist/index.js ...）。更新するには、リポジトリから最新の変更をプルし、npm run build コマンドで再ビルドしてください。

  • エラー: MODULE_NOT_FOUND またはインポートエラー。

    • 原因: 依存関係が正しくインストールされていないか、プロジェクトがビルドされていません。
    • 解決策:
      1. すべての依存関係が存在することを確認するために npm install を実行します。
      2. プロジェクトをコンパイルするために npm run build を実行します。
      3. npm run start でビルドが正常に完了したことを確認します。

  • エラー: 「Operation not permitted」、「Permission denied」または類似のエラー。

    • 原因: サンドボックス機能が有効な場合、Qwen Code がサンドボックス構成によって制限された操作（プロジェクトディレクトリやシステムの一時ディレクトリ外への書き込みなど）を試みることがあります。
    • 解決策: 詳細およびサンドボックス構成のカスタマイズ方法については、構成: サンドボックス のドキュメントを参照してください。

  • 「CI」環境で Qwen Code がインタラクティブモードで動作しない

    • 問題: CI_ で始まる環境変数（例: CI_TOKEN）が設定されている場合、Qwen Code はインタラクティブモードに入らず（プロンプトが表示されず）、非対話的なCI環境であると判断されます。これは、内部UIフレームワークで使用されている is-in-ci パッケージがこれらの変数を検出し、非対話的CI環境であると想定するためです。
    • 原因: is-in-ci パッケージは CI、CONTINUOUS_INTEGRATION、または CI_ 接頭辞を持つ任意の環境変数の存在をチェックします。これらが見つかると、環境が非対話的であることを示し、CLIがインタラクティブモードで起動しないようになります。
    • 解決策: CLIの機能に CI_ 接頭辞付き変数が必要ない場合は、そのコマンドのために一時的に変数を解除できます。例: env -u CI_TOKEN qwen

  • プロジェクトの .env ファイルからの DEBUG モードが動作しない

    • 問題: プロジェクトの .env ファイルで DEBUG=true を設定しても、CLIのデバッグモードが有効になりません。
    • 原因: CLIの動作への干渉を防ぐため、DEBUG および DEBUG_MODE 変数はプロジェクトの .env ファイルから自動的に除外されます。
    • 解決策: 代わりに .qwen/.env ファイルを使用するか、settings.json 内の advanced.excludedEnvVars 設定を調整して除外する変数を減らしてください。

IDE Companion が接続しない

  • VS Code で単一のワークスペースフォルダが開かれていることを確認してください。
  • 拡張機能をインストールした後、統合ターミナルを再起動して以下の環境変数を継承するようにしてください:
    • QWEN_CODE_IDE_WORKSPACE_PATH
    • QWEN_CODE_IDE_SERVER_PORT
  • コンテナ内で実行している場合は、host.docker.internal が解決されることを確認してください。そうでない場合は、ホストを適切にマッピングしてください。
  • /ide install でコンパニオンを再インストールし、コマンドパレットで「Qwen Code: Run」を使用して起動することを確認してください。

終了コード

Qwen Code は、終了理由を示すために特定の終了コードを使用します。これは特にスクリプティングや自動化において有用です。

終了コードエラー種別説明
41FatalAuthenticationError認証プロセス中にエラーが発生しました。
42FatalInputErrorCLI に無効または不足している入力が提供されました。（非対話モードのみ）
44FatalSandboxErrorサンドボックス環境（例：Docker、Podman、Seatbelt）でエラーが発生しました。
52FatalConfigError設定ファイル (settings.json) が無効であるか、エラーを含んでいます。
53FatalTurnLimitedErrorセッションにおける最大会話ターン数に到達しました。（非対話モードのみ）

デバッグのヒント

  • CLI のデバッグ:

    • CLI コマンドで --verbose フラグ（利用可能な場合）を使用して、より詳細な出力を得ます。
    • CLI のログを確認してください。ログは多くの場合、ユーザー固有の設定ディレクトリまたはキャッシュディレクトリにあります。

  • コアのデバッグ:

    • サーバーコンソールの出力でエラーメッセージやスタックトレースがないか確認します。
    • 設定可能であれば、ログの詳細度を上げます。
    • サーバーサイドコードをステップ実行する必要がある場合は、Node.js のデバッグツール（例: node --inspect）を使用します。

  • ツールの問題:

    • 特定のツールが失敗している場合は、そのツールが実行するコマンドまたは操作の最も単純なバージョンを実行することで、問題を切り分けてみてください。
    • run_shell_command の場合は、まずシェルで直接コマンドが動作することを確認してください。
    • ファイルシステムツール については、パスが正しいこと、およびパーミッションを確認してください。

  • プレフライトチェック:

    • コードをコミットする前には常に npm run preflight を実行してください。これにより、フォーマット、リンティング、型エラーなどに関する一般的な問題の多くを検出できます。

あなたに似た既存の GitHub Issues または新しい Issues の作成

この トラブルシューティングガイド で説明されていない問題に遭遇した場合は、Qwen Code の GitHub 上の Issue トラッカー  を検索することを検討してください。あなたの問題に類似した Issue が見つからない場合は、詳細な説明とともに新しい GitHub Issue を作成することを検討してください。プルリクエストも歓迎します！

Last updated on
キーボードショートカット利用規約