「archive integrity check」の対処 — Claude Codeのプラグイン改ざん検知エラー

Plugin archive integrity check failed for <url>: expected sha256 <A>, got <B> — zip配布のプラグインをインストールしようとしてこう出たら、マーケットプレイスのエントリに登録されているsha256と、実際にダウンロードしたファイルのダイジェストが一致しなかったことを意味します。Claude Codeはこの不一致を検知するとインストールを拒否し、プラグインキャッシュには何も反映しません。原因は3通りに絞れます。

「archive integrity check」の意味

Claude Codeのプラグインマーケットプレイスは、archiveソースでzipファイルをHTTPS配布できます。archiveエントリにsha256フィールドを添えておくと、Claude Codeはダウンロードのたびにファイルのダイジェストを計算し、登録値と照合します。一致しなければインストールをその場で止め、プラグインキャッシュのパスには何も書き込みません。壊れたファイルや差し替えられたファイルを、気づかないまま使ってしまう事態を防ぐための仕組みです。

sha256は任意項目です。付けなければこの照合自体が発生しません。付ける場合は64文字の16進数で、大文字小文字どちらでも構いません。

原因は3パターンに絞れる

エラーメッセージ自体は「一致しない」としか言いませんが、原因は次の3つのどれかです。

3パターンとも、インストールする側では直接直せません。原因の特定と修正はマーケットプレイスの公開者側の作業になります。

対処法(プラグインをインストールしている側)

まずマーケットプレイスのカタログを最新化し、公開者がすでに直しているかを確認します。

claude plugin marketplace update <marketplace-name>

更新後に再インストールしても同じ不一致が出るなら、公開者側でまだ修正されていません。マーケットプレイスの公開者に、どのファイルをピンしたつもりだったかを確認してから再度インストールする方が確実です。自分でダイジェストを書き換えて回避することはできません。照合はClaude Code側の固定ロジックです。

エラーメッセージに含まれるexpectedとgotの2つのダイジェストも手がかりになります。expected側がmarketplace.jsonに登録されている値、got側が実際にダウンロードしたファイルから計算した値です。この2つを見比べて、got側が過去に見たことのある別バージョンのダイジェストと一致するなら、公開者がバージョンを上げ忘れたままファイルだけ差し替えた可能性が高いと判断できます。マーケットプレイス全体の仕組みはClaude Codeプラグイン完全ガイドにまとめています。

対処法(プラグインを公開している側)

自分がarchiveソースでプラグインを配布している場合は、URLが実際に配信しているファイルのダイジェストを計算し直します。

shasum -a 256 my-plugin.zip

Windows PowerShellではGet-FileHashを使います。

Get-FileHash -Algorithm SHA256 my-plugin.zip

出力されたダイジェストで、marketplace.jsonのsha256フィールドを上書きします。CDNのキャッシュが古いファイルを返している可能性がある場合は、ダイジェスト計算前にキャッシュを無効化してから、実際に配信されるURLへ直接アクセスして確認してください。手元のファイルと配信URLのファイルが同一であることを確かめてから計算する、という順序が重要です。

versionフィールドを明示している場合は、zipとダイジェストを差し替えた後にバージョン文字列も上げてください。上げないと、すでにインストール済みの利用者はキャッシュされた古いコピーを使い続けます。versionを省略している場合はsha256の値自体が更新シグナルとして働くため、ダイジェストの変更だけで利用者に更新が伝わります。

修正を配布したら、claude plugin validate .をマーケットプレイスのディレクトリで実行し、marketplace.jsonのスキーマ自体に問題が無いかも合わせて確認しておくと安全です。このバリデーターはsha256の値そのものを検証するわけではありませんが、JSON構文エラーや重複したプラグイン名など、別の原因でインストールが失敗するのを事前に防げます。CIでzipをビルドしてダイジェストを自動計算する運用にしておけば、手計算による入力ミスの再発も避けられます。

archiveソースの仕様(まとめて確認)

archiveソースにはsha256の照合以外にも、知っておくと原因の切り分けが速くなる制約があります。

v2.1.120からv2.1.223まではarchiveソース自体はある程度読めるものの、This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.という別のエラーでインストールが止まります。これはダイジェスト不一致ではなく、バージョンが古くてarchiveソースを扱えないという別の原因です。v2.1.120より前ではさらに手前で、archiveエントリを含むマーケットプレイス自体が読み込みに失敗します。同じ「archiveでインストールできない」という症状でも、原因がバージョン起因なのかダイジェスト不一致なのかで表示されるエラーが変わる点を押さえておくと切り分けが早くなります。

マーケットプレイス名自体が問題になる別のエラーもあります。archiveソースの取得に成功する前段階で、マーケットプレイス名がAnthropic向けに予約された名前と衝突していると、そもそもカタログ自体が読み込まれません。詳しくは「Marketplace is registered from an untrusted source」の対処で扱っています。ダイジェスト不一致とは原因の層が異なるため、両方のエラーメッセージを見比べてどちらに該当するかを先に切り分けてください。

認証付きの配布URLでheadersが引き継がれる範囲

社内の限定公開サーバーからzipを配布している場合、extraKnownMarketplaces設定でマーケットプレイスのURLソースにheadersを指定していることがあります。この場合Claude Codeは、archiveダウンロード先のURLがマーケットプレイスURLと同じスキーム・ホスト・ポートであるときだけ、その認証ヘッダーを一緒に送ります。オリジンが異なるURLへのダウンロードにはヘッダーを付けず、リダイレクトでオリジンを離れた時点でもヘッダーを落とします。マーケットプレイスの認証情報が意図せず別のホストへ流出しない設計です。

この挙動を知らずに、マーケットプレイス本体とは別ドメインのCDNへzipを置いていると、認証が必要なURLに対してヘッダーが付かず、ダウンロード自体が401や403で失敗します。この失敗はダイジェスト不一致とは別の症状で、Plugin archive integrity check failedにはなりません。「archiveのダウンロードでエラーになる」ときは、まずダイジェスト不一致なのか認証エラーなのかを区別してください。

区別の手がかりはエラーメッセージの中身です。ダイジェスト不一致は必ずexpected sha256とgotの2つの値を伴って表示されます。認証エラーの場合はHTTPステータスに関する文言が中心で、ダイジェストの比較そのものにたどり着く前に失敗が起きています。どちらの文言が出ているかを確認するだけで、原因の層を素早く切り分けられます。

よくある質問

ダイジェストを消せばインストールできますか

公開者側でsha256フィールドごと削除すれば照合自体が発生しなくなり、インストールは通ります。ただしこれは改ざん検知を無効化する対応なので、意図的にファイルの真正性を保証したい配布物には向きません。恒久対応ではなく暫定回避と考えてください。

大文字小文字の違いで不一致になりますか

なりません。sha256フィールドは大文字小文字どちらの16進数表記も受け付け、Claude Code側の照合も大文字小文字を区別しません。

/plugin installのたびに毎回照合されますか

されます。ダウンロードのたびにダイジェストを計算して照合するため、初回インストールだけでなく更新のたびにも同じチェックが働きます。

GitHubやnpm経由のプラグインでも同じエラーが出ますか

出ません。このエラーはarchiveソース(zip配布)専用です。GitHubリポジトリやnpmパッケージから配布するプラグインは別の仕組みでバージョン管理されており、sha256照合の対象ではありません。

一度失敗したプラグインのキャッシュは残りますか

残りません。ダイジェストが一致しない時点でインストールを拒否するため、Claude Codeはそのファイルをプラグインキャッシュへ一切書き込みません。中途半端に壊れたファイルが手元に残って次回のインストールに影響する、という心配はしなくて構いません。再試行するたびに新しくダウンロードとダイジェスト計算が行われます。

同じzipなのにマシンによって結果が違うことはありますか

通常はありません。ダイジェスト計算はダウンロードしたファイルのバイト列だけで決まるため、実行環境の違いによって結果が変わることはありません。マシンごとに結果が違う場合は、地域によって配信されるCDNのエッジが異なり、実際に違うファイルを受け取っている可能性を疑ってください。

まとめ

「Plugin archive integrity check failed」は、archiveソースのプラグインで、登録されたsha256と実際のダウンロードファイルのダイジェストが一致しないときに出るエラーです。原因はファイルの事後更新・ダイジェストの入力ミス・URLの配信先ズレの3通りに絞れ、いずれも公開者側でしか直せません。インストールする側は/plugin marketplace updateでカタログを最新化してから再試行し、それでも直らなければ公開者に確認します。自分が公開者なら、実際に配信されているファイルをshasum -a 256で計算し直し、sha256と(設定していれば)versionの両方を更新してから再配布してください。