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

トラブルシューティング

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

  • 認証またはログインエラー
  • よくある質問 (FAQ)
  • デバッグのヒント
  • 類似の GitHub Issues の検索または新しい Issues の作成

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

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

  • 問題: 認証失敗後に 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 Personal/Enterprise アカウント）には利用できません。これは、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_TOKEN などの CI_ で始まる環境変数が設定されている場合、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 で Companion を再インストールし、コマンドパレットで「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 Issue または新しい Issue の作成

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

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