claude plugin disableが拒否される原因と、uninstallが止まる理由

claude plugin disableが「required by your organization」で拒否されたら、そのプラグインは組織が必須にしたclaude.ai同期プラグインです。手元の設定では変えられず、直せるのはclaude.aiの組織管理者だけです。claude plugin uninstallが「was not uninstalled」で止まったときは逆で、原因は手元の設定ファイルにあり、自分で直せます。

似た拒否に見えますが、直す人も場所も違います。メッセージの冒頭を読めば、どちらかはすぐ分かります。

2つのメッセージは原因が逆

表の1行目はdisable側、2〜4行目はuninstall側のエラーです。コマンドと取りうるメッセージの組み合わせを頭に入れておくと、切り分けが早くなります。

「required by your organization」で無効化できないとき

メッセージ全文は次の形です。

Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

claude plugin disableでも、/pluginのInstalledタブからの無効化でも、Claude Codeは何も保存せず、プラグインは有効のままです。@syncedという名前から分かるとおり、対象はclaude.aiアカウントから端末に同期されたプラグインです。マーケットプレイスから入れたプラグインではありません。

必須にされたプラグインは、無効化しても戻ってくる

組織がclaude.ai側で必須にしたプラグインは、以前に自分で無効化していても読み込まれます。claude plugin listではrequired by your orgと表示されるので、拒否される前にどれが必須か確認できます。

claude plugin list

同期プラグインはSynced from claude.aiのグループに並びます。無効化したいときは名前に@syncedを付けて指定します。

claude plugin disable formatter@synced

必須でないプラグインなら、この1行でユーザー設定のenabledPluginsに"formatter@synced": falseが保存されます。必須の場合だけ、上のメッセージで止まります。

必須プラグインが依存するプラグインも同じ

無効化したいプラグインを、必須プラグインが依存先として使っている場合も、Claude Codeは同じ形で拒否します。このとき、メッセージには必要としている必須プラグインの名前が入ります。自分が無効化しようとしたのは必須でないプラグインなのに拒否された、という場面はこの経路を疑えます。

直す手段は管理者側にある

Claude Codeのエラーリファレンスに載っている対処は1つだけです。claude.aiの組織の管理者に、そのプラグインの必須設定を変えてもらいます。端末側でsyncClaudeAiPluginsをfalseにして同期ごと止める方法は別記事にありますが、必須プラグインにその設定がどう効くかは、同期プラグインのページに記載がありません。必須を外す依頼を先に出すのが筋の通った順番です。

一方、組織側が管理設定でsyncClaudeAiPluginsを決めている場合、端末のユーザー設定では上書きできません。管理設定側の構成はプラグインマーケットプレイスの必須化の記事の対象です。

「was not uninstalled」でuninstallが止まるとき

claude plugin uninstall、または/pluginのInstalledタブのUninstallが、"<plugin>" was not uninstalled:で始まるメッセージで止まるケースです。Claude CodeはenabledPluginsからプラグインの項目を外したあと、そのスコープの設定ファイルを読み直します。そこでまだ有効の記述が見つかるか、有効にしうるファイルを確認できないと、アンインストールを中断します。

なぜ中断するのか

有効にする記述が残ったまま、プラグインの保存済みオプション・シークレット・データを消すと、設定が復活させたときに失われたものを戻せません。そこで、プラグインはインストールされたままにして、保存した内容も消しません。エラーに見えて、実際はデータを守る動きです。

メッセージの中ほどは、ファイル名と原因を示します。

• it is still switched on in <file>, although the settings change reported no error: 書き込みは成功と返ったのに、読み直すと項目が残っている
• it is still switched on in <file>, and the settings change failed (<error>): 保存に失敗した。理由は括弧内
• <file> is there and could not be read: 読めない。たとえばJSONとして不正で、有効にしている可能性が残る
• <file> (not read: it is on a network path or is a link to one, or could not be checked): ネットワーク上のパス(へのリンク)か、確認できなかったため読まなかった

最後の形は、プロジェクトやローカルの設定ファイル、またはそれを含む.claudeフォルダがネットワークの場所を指すリンクのときに出ます。

直し方

メッセージの最終文に従います。名指しされたファイルを直すか置き換え、enabledPluginsからそのプラグインの行を自分で消して、もう一度アンインストールを実行します。たとえば次のような設定が残っていたとします。

{
  "enabledPlugins": {
    "formatter@my-marketplace": true
  }
}

この行を消してから再実行します。プロジェクトに入れたプラグインなら、--scopeを忘れないでください。uninstallの既定のスコープはuserで、プロジェクトのスコープは明示が必要です。

claude plugin uninstall formatter@my-marketplace --scope project

成功するとSuccessfully uninstalled plugin: formatter (scope: project)と出ます。プラグインがそのスコープに入っていない場合はFailed to uninstall plugin ...:で始まる行が出て終了コード1になります。スコープの付け間違いも、この形で見分けられます。

スクリプトから見分ける

--jsonを付けると、結果が標準出力の最終行に1つのJSONオブジェクトとして出ます。設定ファイル起因の中断はfailureCode: "settings_still_on"です。CIなどで判定する場合は、たとえば次のようにします(jqで読む一例です)。

claude plugin uninstall formatter --json | tail -n 1 | jq -r .failureCode

--jsonはv2.1.268以降、設定ファイルを読み直す確認はv2.1.282以降が必要です。詳しくはv2.1.282の記事にまとめています。

必須プラグインが読み込まれる条件

必須プラグインが見えるかどうかは、サインインの方法で変わります。端末のセッションで同期が動くのは、claude.aiアカウントでサインインしたセッションだけです。次のセッションでは、/loginをやり直しても同期プラグインを読み込みません。

• ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_OAUTH_TOKEN、apiKeyHelperのスクリプトが認証情報を供給しているセッション
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICなどで、Anthropicからフィーチャーフラグを取得しないセッション
• bareモード、または--safe-modeで起動したセッション
• --setting-sourcesの一覧からuserを外したセッション

同期はClaude Codeの起動時にバックグラウンドで1回走ります。追加・更新・削除が起きるとPlugins changed. Run /reload-plugins to activate.と出るので、/reload-pluginsで反映できます。同期にはv2.1.273以降が必要です。職場の端末で必須プラグインが見えるのに、自分のCIでは見えない、という差は、この条件表で説明がつくことがあります。

必須が絡まない無効化の拒否

claude plugin disableが止まる理由は、組織の必須設定だけではありません。別の有効なプラグインが対象に依存している場合も、コマンドは失敗し、先に無効化すべき依存元の名前を示します。この場合は、メッセージの名前を先に無効化すれば通ります。

状態を戻すときのclaude plugin enableにも対称の失敗があります。依存先がインストールされていない場合や、組織のプラグインポリシーでブロックされている場合、より優先度の高いスコープでfalseにされている場合です。最後のケースでは、そのスコープで依存先を有効にするか、--scopeでそこへ書き込みます。

installed_plugins.jsonが原因のとき

メッセージの:のあとが設定ファイル名でなくinstalled_plugins.jsonで始まるときは、別の原因です。installed_plugins.jsonに、いま使っているバージョンのClaude Codeが読めない記録が入っています。別のバージョン、とくに新しいバージョンが書いた可能性が高いとされています。

この状態では、Claude Codeはファイルを書き換えないため、記録は失われません。メッセージの選択肢は次の順で試します。

1. claude updateでClaude Codeを更新する
2. 更新できないなら、その記録を書いたバージョンのClaude Codeでプラグインをアンインストールする
3. どちらも駄目なら、installed_plugins.jsonから該当の記録を手で削除し、再起動するか/reload-pluginsを実行する

同じ原因でinstallとupdateも止まり、--jsonではfailureCode: "install_records_unreadable"になります。アンインストールだけの問題ではない点が、設定ファイル起因との見分けどころです。

無効化とアンインストールの使い分け

同期プラグインにはマーケットプレイスもインストール記録もありません。Claude Codeが同期して<name>@syncedとして読み込むだけの存在です。止める手段は、claude plugin disable <name>@syncedと、claude.ai側での設定変更です。マーケットプレイスから入れたプラグインは、disableなら残して止め、uninstallなら保存データごと消します。導入経路ごとの違いはclaude plugin installの導入経路の記事に、Claude Code本体の削除はアンインストール手順にあります。

uninstallでは保存データも消えるので、あとで戻す可能性があるなら--keep-dataでデータディレクトリを残せます。disableは何も消さずに止める操作で、拒否されても失うものはありません。