marketplace entry pathが拒否される原因 — Claude Codeプラグインの対処

claude plugin install が次のメッセージで止まるとき、原因はプラグインの中身ではなく、マーケットプレイス側の marketplace.json に書かれた source の書き方にあります。

Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (…)

このエラーは「エントリが指す場所を、マーケットプレイスのディレクトリの内側に解決できない」という拒否です。原因は4つの型に分かれ、どれに当たるかでマーケットプレイスの管理者が直すのか、利用者が追加の仕方を変えるのかが分かれます。

まず自分の症状を2つのメッセージで見分ける

同じ原因で、状況によって別の文言が出ます。

後者には「Check that the marketplace entry has a plain relative path」という案内が付き、素直な相対パスに直すよう促されます。どちらも同じ検査に落ちた結果なので、直し方は共通です。

拒否される書き方と直し方

エラーリファレンスは、拒否の対象を次のように挙げています。

1〜3枚目は source の書き方そのものを直す話で、以下の小見出しで順に扱います。4枚目のURL直指定は直し方が別なので、その後の節にまとめています。

絶対パスと .. で外へ出る書き方

相対パスの基準は、.claude-plugin/ ではなく、それを含むディレクトリ(マーケットプレイスルート)です。./plugins/formatter は <root>/plugins/formatter に解決されます。ルートの外へ出る .. は検証でも弾かれ、claude plugin validate は次の形で報告します。

plugins[i].source: Path contains "..": <path>

隣のリポジトリのプラグインを使いたくなっても、../other-repo/plugin は書けません。別リポジトリのプラグインは github や git-subdir などのオブジェクト形式で指定します。形式ごとの違いはプラグインソースの使い分けにまとめています。

./ を付け忘れた書き方は別のエラーになる

./ なしの相対パス(plugins/formatter)は、このエラーとは別に Invalid string: must start with "./" で止まります。例外は "."(ルート自身)と、metadata.pluginRoot を設定したうえでの裸のディレクトリ名("formatter")です。team-a/formatter のようにスラッシュを含む名前は裸の名前にならず、pluginRoot があっても ./ が要ります。裸の名前の書き方は後ろの節で扱います。

macOSとLinuxのバックスラッシュ

Windows由来のパスをそのまま貼ると起きます。

{ "name": "formatter", "source": ".\\plugins\\formatter" }

macOSとLinuxのClaude Codeは、先頭の ./ より後ろにバックスラッシュがあるエントリを拒否します。Windowsのエディタや補完で \ 区切りになったファイルをチームで共有している場合、Windowsの利用者だけ入れてmacOS側だけ入れられない、という見え方になる可能性があります。Windows側の挙動はエラーリファレンスに記載がありません。マーケットプレイスは区切りをスラッシュにそろえておくのが確実です。

{ "name": "formatter", "source": "./plugins/formatter" }

シンボリックリンクで外へ出る

リモートのマーケットプレイス(gitやURLで取得したもの)では、エントリがシンボリックリンクを経由してマーケットプレイスのディレクトリの外へ解決される場合も拒否されます。モノレポで共通ディレクトリを ln -s で共有している構成は、ローカルの directory として追加すると動き、リモート取得に切り替えた途端に落ちる、という形で表面化し得ます。

マーケットプレイスの管理者は、リンクがマーケットプレイスの内側を指すように保つか、リンクを実体のディレクトリに置き換えます。

claude plugin validate には、ローカルの source がリンクであるとき Local source "x" is or traverses a symlink, so <path> was not read という警告があります。公開前に検査しておくと、このエラーの手前で気づけます。

URLで追加したマーケットプレイスは相対エントリが解決できない

利用者側で出会いやすいのがこの型です。https://example.com/marketplace.json のようなURLでマーケットプレイスを追加すると、Claude Codeはその marketplace.json だけを取得します。プラグインのファイルは取得されないので、./plugins/my-plugin が指す先のディレクトリが手元に存在せず、同じメッセージで拒否されます。

追加元の種類ごとの扱いは次のとおりです。

settings は extraKnownMarketplaces などで設定ファイルに直接カタログを書く形式です。この形式のエントリは、リポジトリを持たないのでオブジェクト形式で書く必要があります。チーム配布の設定はextraKnownMarketplacesで扱っています。

マーケットプレイスの管理者側の直し方

URLで配るなら、各エントリを単体で取得できる形にします。

{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

もう1つは、マーケットプレイスをgitリポジトリでホストし、利用者にリポジトリのURLで追加してもらう方法です。gitソースはリポジトリ全体をクローンするので、相対パスがそのまま解決されます。

利用者側の直し方

マーケットプレイスの作者に別のソース形式を使うよう頼むか、同じマーケットプレイスがgitリポジトリでも公開されているなら、そちらのURLで追加し直します。追加済みの名前が残っていると別のエラーが出ることがあるので、手順はMarketplace is already added from a different sourceを参照してください。

管理者が公開前に確かめる手順

エラーは利用者がインストールしたあとに出ます。公開前にはローカルで次を実行します。

cd path/to/marketplace-root
claude plugin validate .

claude plugin validate はマーケットプレイスのルートか、マーケットプレイスファイルそのものを受け取ります。.. の混入、./ 抜け、リンク経由のエントリは検証で見つかります。一方、ソースの取得エラーはインストール後にしか出ないと明記されているため、URL追加と相対エントリの組み合わせは検証では拾えません。公開形態に合わせて、実際に追加とインストールまで試すのが確実です。

ローカルのディレクトリは、パスを渡すとその場で読み込まれます。次のように追加してからインストールを試すと、手元の編集がそのまま反映されます。

claude plugin marketplace add ./my-marketplace
claude plugin install formatter@my-marketplace

ただし外へ抜けるリンクの拒否は、リモート取得したマーケットプレイスに対する記述です。リンクとURL追加の相対エントリは、公開形態と同じ追加方法で確かめます。

メッセージ末尾のカッコが原因の一覧になっている

install のメッセージは、カッコの中に拒否の理由をまとめて持っています。読み方を押さえると、どの型か見当が付きます。

カッコ内は原因の候補を並べた文言で、今回の1件がどれに当たるかは書かれていません。そのため、先に追加元の種類(URLかgitか)を確かめ、次に source の文字列を見る順で絞ります。

裸のディレクトリ名で書き直す選択肢

エントリが多く、./plugins/ を毎回書く構成では、metadata.pluginRoot で共通の親を指定できます。pluginRoot 自身もマーケットプレイスの内側を指す相対パスでなければなりません。

{
  "name": "my-marketplace",
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    { "name": "formatter", "source": "formatter" }
  ]
}

この例では "formatter" が ./plugins/formatter に解決されます。裸の名前を使えるのはClaude Code v2.1.239以降です。pluginRoot は ./ で始まるエントリには効きません。

関連しやすい別のエラーとの見分け方

似た見た目で原因が違うものが3つあります。

• Plugin directory not found at path: <path>: 相対パスの形式は正しいが、そのディレクトリが存在しない。エントリの source を直すか、フォルダを戻します
• Marketplace directory not found at path: <path>: マーケットプレイス自身のディレクトリが移動または削除された。ローカルパスで追加したマーケットプレイスで起きます
• path escapes plugin directory: プラグインの中のコンポーネントのパスがプラグインルートの外に出ている。マーケットプレイスのエントリではなく、プラグイン内部の問題です

最後の1つは、プラグイン内部のパス解決を扱うプラグインの環境変数とパス解決の領分です。marketplace add そのものが失敗する場合はmarketplace addが失敗する原因と対処に分けています。

切り分けの順番

全体像はClaude Codeプラグイン完全ガイドにあります。

まとめ

このエラーが示すのは、エントリがマーケットプレイスの内側に解決できないという一点です。絶対パス・..・ネットワークパス風の表記・macOS/Linuxでのバックスラッシュ・外へ出るリンク・URL直指定の相対エントリのどれかに当たります。直す側は、URL配布ならオブジェクト形式のソースへ、それ以外ならスラッシュ区切りの ./ 始まりの相対パスへそろえる作業になります。