Commerce Version Toolのトラブルシューティング
このページでは、Composer検出、レジストリの読み込み、内部ドライラン パッチ検出、出力生成、監査ログに関する一般的なCommerce Version Tool （CVT）の問題のトラブルシューティングを行います。
クイックトラブルシューティング手順
CVT ツールが期待されるパッチ ステータス レポートを返さない場合：
- 対象のインストールで、サポートされているAdobe Commerce バージョンとエディションが使用されていることを確認します。
composer.lockが存在し、検査する環境と一致することを確認してください。- PHPとシステム
patchバイナリが使用可能であることを確認します。 - CVTがパッチ レジストリ ファイルを読み取れることを確認します。
- 出力の
warnings、missing_patchesおよびunknown_patchesを確認してください。 - ログ ファイルが作成されている場合は、実行の監査概要を
var/log/patch_status.logで確認してください。
一般的な問題と解決策
基本バージョンを検出できません
CVT ツールでAdobe Commerceの基本バージョンが見つからない場合は、次の条件を確認します。
確認：
composer.lockが見つかりません。patch-statusコマンドがAdobe Commerce プロジェクトのルート外で実行されているため（または--rootが間違ったパスを指しています）、composer.lockが見つかりません。composer.lockは存在しますが、有効なJSONでないか、読み取ることができません。composer.lockには、認識された基本パッケージ （magento/product-enterprise-edition、magento/product-community-edition、magento/magento2-base）が含まれていません。
警告メッセージ：
composer.lockが存在するが、読み取り不可能であるか、解析できないか、認識された基本パッケージを含まない場合、ツールは警告出力フィールドに次のいずれかの文字列を出力します。
No recognized Commerce base package found in composer.lock
composer.lock exists but could not be read
composer.lock could not be parsed as JSON
composer.lockが完全に見つからない場合、ツールはbase_version: "unknown"を報告し、警告メッセージはまったくありません。 常に出力のbase_versionを直接確認してください。 この問題を見つけるために警告の存在に依存しないでください。前述の条件のいずれかは、ツールが基本バージョンを検出できないことを示します。 ツールはコード 1で終了し、パッチ検出は実行されません。
アクション：
- Adobe Commerce プロジェクト ルートから
patch-statusコマンドを実行するか、正しい--rootを渡します。 composer.lockが存在し、現在の有効なJSONであることを確認します。- インストールでサポートされているAdobe Commerce エディションを使用して、
composer.lockに認識された基本パッケージの1つが含まれていることを確認してください。
インストールされたバージョンにはパッチは適用されません
CVTが有効なbase_versionを報告していますが、applied_patches、missing_patches、unknown_patchesが空の場合、インストールされているバージョンは現在のパッチレジストリの対象にはなりません。
確認：
- インストールされているAdobe Commerce バージョンは、パッチ レジストリ ファイルに表示されません。 例えば、レジストリの最新のエントリよりも新しいリリースを指定します。
警告メッセージ：
No patches found in registry for installed component versions (CE=2.4.7-p9)
この警告は、「基本バージョンを検出できません」と異なります。 base_versionは正しく、ツールは0を終了し、レジストリには比較するものがありません。
アクション：
- 出力の
base_versionが期待どおりであることを確認してください。 registry_sourceが古いものではなく、remoteまたは最近のcacheであることを確認してください。- このバージョンを既にカバーする必要がある場合は、Adobe Commerce サポートにお問い合わせください。
パッチレジストリを取得できません
CVT ツールが最新のパッチ レジストリ ファイルを取得できない場合は、ネットワークとキャッシュの設定を確認します。
確認：
- ネットワークは利用できません。
- Adobe パッチエンドポイントリクエストがタイムアウトします。
--no-cacheが使用されたため、リモート レジストリにアクセスできません。PATCH_REGISTRY_URLは、使用できないレジストリを指しているか、有効なHTTPS URLではありません。- CVT ツールが最新のパッチ レジストリ ファイルを取得できない場合は、ネットワークとキャッシュの設定を確認します。
警告メッセージ：
このツールは、このシナリオの警告出力フィールドに次の文字列を出力します。
Remote registry fetch failed (HTTP 403). Check PATCH_REGISTRY_URL (if set) and network connectivity.
Remote registry response was not valid JSON; ignoring.
Could not load remote registry. Using cached registry (3 hours old). CVE coverage may be incomplete.
Patch registry could not be loaded.
Could not fetch remote registry and --no-cache was set; aborting.
古いキャッシュメッセージには、実際の経過時間（時間）が含まれます（例：(3 hours old)）。
patch registry could not be loadedとcould not fetch remote registryの警告は、パッチ検出を実行せずにツールが終了したことを示します。
アクション：
- ネットワーク接続が利用可能な場合は、
patch-statusコマンドを再実行します。 - 古いキャッシュ警告がスキャンで許容される場合は、CVT ツールでキャッシュ レジストリを使用できるようにします。
- 新しいリモートフェッチが必要でない限り、
--no-cacheを削除します。 - レジストリ キャッシュを再利用する場合は、CVT ツールが
var/patch_metadata/に書き込むことができることを確認してください。
パッチの差分を取得または検証できません
CVT ツールで1つ以上の適用可能なパッチをテストできない場合は、パッチ差分アクセスを確認します。
確認：
- Adobe パッチエンドポイントからパッチの差分をダウンロードできません。
- 認証されたパッチのダウンロードに必要な資格情報が見つからないか、無効です。
PATCH_DIFF_BASE_URLは、利用できないパッチの差分ソースを指しているか、有効なHTTPS URLではありません。- キャッシュされたパッチの差分が見つからないか、読み取れません。
- ダウンロードしたパッチの差分に対するSHA-256検証が失敗します。
- CVT ツールは
var/patch_metadata/.patch_diffs/に書き込めません。
警告メッセージ：
このツールは、このシナリオの警告出力フィールドに次の文字列を出力します。
Patch 247p9-2026-05-001-EE requires authentication. Set credentials via COMPOSER_AUTH or auth.json.
Could not fetch patch 247p9-2026-05-001-EE (HTTP 401). Check credentials (COMPOSER_AUTH / auth.json).
Could not fetch patch 247p9-2026-05-001-EE (HTTP 404).
Could not fetch or verify patch 247p9-2026-05-001-EE. Check network connectivity and credentials (COMPOSER_AUTH / auth.json).
Could not fetch patch file for 247p9-2026-05-001-EE.
SHA-256 verification failed for patch 247p9-2026-05-001-EE; discarding download.
各メッセージのパッチ IDは、実際のレジストリ エントリ ID （例：247p9-2026-05-001-EE）です。 SHA-256 verification failedは、新しくダウンロードされたパッチファイルが、想定されるチェックサムと一致しなかったことを意味します。 ツールはキャッシュせずに破棄し、この実行のパッチ unknownを分類します。 破損したローカル キャッシュ エントリが検出され、警告なしで同じ実行内でサイレントに再フェッチされます。 どちらの場合も、手動によるキャッシュのクリーンアップは必要ありません。
アクション：
- ネットワーク接続を確認し、コマンドを再試行してください。
- 認証されたパッチのダウンロードに必要な資格情報が設定されていることを確認します。
- CVT ツールが
var/patch_metadata/.patch_diffs/に書き込むことができることを確認します。 - パッチが不明として分類されたままの場合は、警告と出力の詳細を保持します。
環境にないパッチまたは不明なパッチが報告される
レポートに予期しないmissing_patchesまたはunknown_patches値が含まれる場合は、インストールと出力の詳細を確認します。
確認：
- 毎月のパッチが順番に適用されました。
- Adobe Commerce Business-to-Business （B2B）やAdobe Commerce Page Builderなどのコンポーネント固有のパッチがありません。
composer.lockは、パッチが必要なインストール済みコンポーネントバージョンを報告します。- パッチの差分が利用できないか、検出結果が決定的ではありません。
警告メッセージ：
このツールは、このシナリオの警告出力フィールドに次の文字列を出力します。
No file_name or sha256 for 247p9-2026-05-001-EE
Registry entry '247p9-2026-05-001-EE' requires unknown patch '247p9-2026-04-001-EE'; skipping.
descendant diffs unavailable for 247p9-2026-06-001-EE; dry-run for 247p9-2026-05-001-EE may be inaccurate
Failed to reverse-apply 247p9-2026-06-001-EE when preparing dry-run for 247p9-2026-05-001-EE; result may be inaccurate
Failed to forward-apply prerequisite 247p9-2026-04-001-EE when preparing dry-run for 247p9-2026-05-001-EE; result may be inaccurate
警告でmay be inaccurateが発生した場合、ドライラン チェックは実行されますが、信頼性は低下します。 パッチは引き続きapplied_patchesまたはmissing_patchesに分類でき、必ずしもunknown_patchesとは限りません。
不明なパッチの場合、具体的には、var/log/patch_status.logは生のパッチドライラン出力（前方及び逆）を記録し、どのファイルとチャンクが一致しなかったかを示します。
「パッチが見つかりません」という警告が表示された場合は、 インストールされているバージョンにパッチが適用されないを参照してガイダンスを受けてください。
アクション：
applied_patches、missing_patches、unknown_patchesのフィールドを確認します。- インストールされているエディションとコンポーネントに欠落しているパッチが適用されるかどうかを確認します。
- その結果と、関連するセキュリティ パッチのリリースノートを比較します。
- 検査したコードベースが、レポート対象のデプロイ済み環境と一致することを確認します。
- 不明なステータスが是正計画をブロックする場合は、Adobe Commerce サポートにお問い合わせください。
出力が生成されない
CVT ツールが完了しても、予期されるJSONまたはCSV出力が見つからない場合は、コマンドの構文とターミナル出力を確認します。
アクション：
- CSV出力が必要ない場合は、デフォルトのJSON出力を使用します。
--format=csvを使用してCSV出力を生成します。- コマンド出力が、CVT ツールを実行するシェル、スクリプト、またはスキャナーによってリダイレクトまたは破棄されないことを確認します。
stderrでpatch-status:個のエラーメッセージを確認してください。- 出力をファイル （例：
patch-status > report.json）にリダイレクトする場合は、シェルがその宛先に対する書き込み権限を持っていることを確認します。 ツールはstdoutにのみ書き込みます。 - CVT ツールが
var/log/patch_status.logに書き込むことができることを確認します。 - コマンドを再実行し、端末出力をキャプチャしてトラブルシューティングを行います。
ヘルプの取得
Adobe Commerce サポートに連絡する場合は、問題を調査するために必要な詳細情報のみを提供してください。
次を含める：
- Adobe Commerceのバージョンとエディション
- CVT ツール バージョン
- CVT ツール出力のレジストリ ソース
- 関連する
applied_patches、missing_patchesおよびunknown_patches値 - 関連する警告
- エラーメッセージまたはコマンド出力
共有ログまたは添付ファイルに、シークレット、資格情報、秘密鍵、または関連しない顧客データを含めないでください。