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

トラブルシューティング

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

  • 認証またはログインエラー
  • よくある質問（FAQ）
  • デバッグのヒント
  • あなたの問題に類似した既存の GitHub Issues の検索や新しい Issue の作成方法

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

  • エラー: 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 個人／エンタープライズアカウント）には提供されていません。これは、Qwen Code Assist API がキャッシュされたコンテンツの作成に対応していないためです。/stats コマンドを使用して、引き続き合計トークン使用量を確認できます。

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

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

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

  • エラー: qwen コマンド実行時に「Command not found」になる

    • 原因: 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 はインタラクティブモードに入らず（プロンプトが表示されない）、これは基盤となる 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 のデバッグモードが有効になりません。
    • 原因: DEBUG および DEBUG_MODE 変数は、CLI の動作への干渉を防ぐために、プロジェクトの .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トラッカー を検索してみてください。あなたと同じ問題が見つからない場合は、詳細な説明を添えて新しいGitHub Issueを作成することを検討してください。プルリクエストも歓迎します！

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