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

トラブルシューティング

このガイドでは、以下のトピックを含む一般的な問題の解決方法とデバッグのヒントを提供します。

  • 認証またはログインエラー
  • よくある質問（FAQ）
  • デバッグのヒント
  • 類似の既存 GitHub Issue の確認、または新しい 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（アドレスが既に使用中）

    • 原因: 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 または import エラー

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

  • エラー: 「操作が許可されていません」、「アクセスが拒否されました」など

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

  • CI 環境で Qwen Code がインタラクティブモードで実行されない

    • 問題: CI_ で始まる環境変数（例: CI_TOKEN）が設定されていると、Qwen Code はインタラクティブモードに入らず（プロンプトが表示されません）。これは、基盤となる UI フレームワークが使用する is-in-ci パッケージがこのような環境変数を検出し、非インタラクティブな CI 環境であると判断するためです。
    • 原因: is-in-ci パッケージは、CI、CONTINUOUS_INTEGRATION、または CI_ で始まる任意の環境変数の存在をチェックします。これらのいずれかが検出されると、その環境が非インタラクティブであると判断され、CLI がインタラクティブモードで起動しなくなります。
    • 解決方法: CI_ で始まる環境変数が CLI の動作に不要な場合、コマンド実行時に一時的に無効化できます。例: env -u CI_TOKEN qwen

  • プロジェクトの .env ファイルから DEBUG モードが有効にならない

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

IDE コンパニオンが接続できない

  • 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 のログを確認します。ログは通常、ユーザー固有の設定ディレクトリまたはキャッシュディレクトリ内にあります。

  • コア部分のデバッグ:

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

  • ツール関連の問題:

    • 特定のツールが失敗する場合、そのツールが実行するコマンドまたは操作の最も単純なバージョンを実行して、問題を切り分けます。
    • run_shell_command の場合は、まず対象のコマンドがシェル上で直接正しく動作することを確認します。
    • ファイルシステムツール の場合は、パスが正しいことを確認し、アクセス権限も確認します。

  • 事前チェック（プリフライトチェック）:

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

類似の既存 GitHub Issue の確認または新規 Issue の作成

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

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