플러그인 문제 해결

기준일: 2026-10-23
공식 기준: Troubleshoot plugins

개요

Claude Code 플러그인과 마켓플레이스(플러그인을 설치하는 카탈로그)의 오류 메시지와 증상을 모았습니다. 각 항목은 원인, 해결 하나, 해결 후 보이는 결과를 줍니다. 메시지가 플러그인/마켓 이름을 담는 곳은 <name> 같은 placeholder로 표기합니다. 설치하는 사람, 만드는 사람, 마켓을 호스팅하는 사람, 조직 관리자 모두 대상입니다.

받은 메시지를 정확히 검색하세요. 각 메시지는 그것을 만든 단계 아래에 있으며 실행한 명령과 다를 수 있습니다 (예: 마켓이 없어서 설치가 실패하면 마켓 추가 단계에 있음).

다른 페이지: 스코프·캐시·우선순위가 그렇게 동작하는 이유는 Plugin loading reference, 플래그·필드·명령 조회는 plugin commands reference·manifest reference·marketplace reference. hooks module not loaded/hooks module did not load는 플러그인이 mod라는 뜻이므로 The mod doesn't load.

핵심 개념

단계	다루는 것
/plugin 실행 위치	패널을 열 수 없는 곳, 존재하지 않는 명령 철자
마켓 추가	marketplace add 실패, 새로고침 실패
플러그인 설치	설치 중 메시지, /plugin Errors 탭, 빈 Discover 탭
설치 후 미동작	skill·hook·서버가 동작하지 않음
플러그인 개발	--plugin-dir, 경로, 검증
마켓 호스팅	소유자용 검증 오류
조직 정책 차단	관리자 설정 때문에 거부

상세

/plugin 실행 위치

/plugin은 실행 중인 Claude Code 터미널 세션 안에서 입력하는 명령이며 대화형 패널을 엽니다.

/plugin isn't available in this environment

패널을 그릴 터미널이 없는 세션에서 입력했습니다: 비대화 모드 claude -p, Agent SDK, Claude 데스크톱 앱 Code 탭, VS Code 확장 패널, claude.ai/code 브라우저. VS Code 확장 패널에서는 뒤에 무언가가 붙은 /plugin ... 줄(예: /plugin install <plugin>@<marketplace>)만 이 응답을 받고, /plugin 또는 /plugins 단독은 Manage plugins 대화상자를 엽니다. 있는 곳에서 설치하세요.

• Claude 데스크톱 앱 로컬/SSH 세션: Install a plugin의 Desktop app 탭
• VS Code 확장: 같은 곳의 VS Code 탭
• Claude Code on the web 또는 데스크톱 cloud 세션: cloud 세션에는 플러그인 브라우저가 없음. 로드되는 것은 Cloud session 탭
• 접근 가능한 터미널: claude 실행 후 /plugin, 또는 세션 없이 셸에서 claude plugin install <plugin>@<marketplace>

터미널 설치가 성공하면 /plugin은 ✓ Installed <plugin>.으로 시작하는 요약을, claude plugin install은 Successfully installed plugin: <plugin>@<marketplace>를 출력합니다.

zsh: no such file or directory: /plugin

셸 프롬프트에 /plugin ...을 입력했습니다 (Bash는 bash: /plugin: No such file or directory). 세션을 시작해 거기서 입력하세요.

claude

/plugin install <plugin>@<marketplace>

설치가 이후 실패하면 메시지는 마켓 추가나 플러그인 설치 아래에 있습니다. 세션 없이 설치하려면 claude plugin install <plugin>@<marketplace>.

The term '/plugin' is not recognized as the name of a cmdlet

PowerShell 프롬프트에 입력했습니다. claude를 실행해 Claude Code 프롬프트에서 /plugin을 입력하거나, PowerShell에서 claude plugin install <plugin>@<marketplace>를 실행하세요.

claude: command not found after claude plugin ...

셸이 claude 자체를 찾지 못합니다. Windows 메시지는 'claude' is not recognized as the name of a cmdlet 또는 'claude' is not recognized as an internal or external command. 원인은 플러그인 명령이 아닙니다. Verify your PATH 후 다시 시도하세요.

Unknown command와 존재하지 않는 명령 철자

세션에서 Unknown command: /<name>, 셸에서 error: unknown command '<name>' 또는 error: unknown option '<flag>'가 나옵니다. plugin commands reference가 하위 명령과 플래그를 나열합니다.

입력한 것	Claude Code 응답	대신 사용
claude plugin add <source>	error: unknown command 'add'	마켓 추가는 claude plugin marketplace add <source>, 플러그인 설치는 claude plugin install <plugin>@<marketplace>
claude plugin install <plugin> --project	error: unknown option '--project'	claude plugin install <plugin>@<marketplace> --scope project
/install <plugin>	Unknown command: /install	/plugin install <plugin>@<marketplace>
/plugin add <source>	/plugin 패널이 Discover 탭으로 열림	/plugin marketplace add <source>
소스로 marketplace.anthropic.com	Invalid marketplace source format. Try: owner/repo, https://..., or ./path	공식 마켓은 anthropics/claude-plugins-official

틀려 보이지만 동작하는 철자: claude plugins는 claude plugin의 별칭, claude plugin remove는 claude plugin uninstall의 별칭, 세션의 /plugins와 /marketplace는 /plugin과 같은 패널을 엶.

마켓 추가

마켓은 git 저장소, URL, 로컬 경로에서 추가하는 카탈로그입니다. 추가가 실패하거나 이후 새로고침이 실패할 때의 메시지입니다.

Marketplace "claude-plugins-official" not found

세션에서 /plugin install <plugin>@claude-plugins-official을 실행했는데 그 이름의 마켓이 없습니다. 공식 마켓이 아직 이 기기에 등록되지 않았습니다. Claude Code는 보통 첫 인터랙티브 터미널 세션 시작 때 스스로 등록하지만, VS Code 확장으로만 썼거나, 정책이 소스를 막거나, CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL이 설정됐거나, 재시도 대기 중인 실패 시도 뒤에는 건너뛰거나 미룹니다. claude plugin 셸 명령은 등록해 주지 않습니다. 추가 후 재시도:

/plugin marketplace add anthropics/claude-plugins-official

Successfully added marketplace: claude-plugins-official이 출력되고 /plugin marketplace list에 소스와 함께 나옵니다. 같은 문자열이 settings에 나열된 플러그인이 추가하지 않은 마켓을 지목할 때 /plugin Errors 탭(로드 실패 목록)에도 나타납니다.

Marketplace "<name>" not found

세션에서 /plugin install을 실행했는데 그 이름의 마켓이 없습니다. 두 형태가 이 메시지에 닿습니다.

• /plugin install <plugin>@<name>: 추가하지 않은 마켓을 지목. 찾아서 추가
• 경로·URL·owner/repo로 /plugin install <source>: 이미 추가한 소스여도 설치 대신 이 메시지. 한 명령으로 설치하려면 Add a marketplace and install in one command

이름이 claudeai-로 시작하면 claude.ai에서 호스팅되는 마켓이며 셸에서 claude plugin marketplace add --claudeai <name>으로 이름으로 추가합니다 (Add a marketplace from claude.ai). 그 외 이름은 install 줄이 마켓 호스팅 위치를 알려 주지 않고 Claude Code에 마켓 이름을 조회할 색인도 없으므로, 보낸 사람에게 소스(GitHub owner/repo, git URL, 경로)를 물어 마켓을 추가한 뒤 install 줄을 다시 실행하세요. 누가 보낸 마켓은 서드파티이므로 설치 전에 검토하세요. 이미 추가했다면 /plugin marketplace list와 철자를 비교하세요.

Invalid marketplace source format

/plugin marketplace add <source>, claude plugin marketplace add <source>, claude plugin install <plugin> --marketplace <source>에서 Invalid marketplace source format. Try: owner/repo, https://..., or ./path가 나옵니다. 허용 형태:

• GitHub owner/repo 단축형
• https:// 또는 http:// URL
• user@host:path SSH URL
• ./, ../, /, ~로 시작하는 로컬 경로

claude-plugins-official 같은 bare 이름이나 marketplace.anthropic.com 같은 bare 호스트 이름은 맞지 않습니다. 예: /plugin marketplace add anthropics/claude-plugins-official. 성공하면 Successfully added marketplace: <name>.

'<source>' is not a valid GitHub owner/repo shorthand

github.com/owner/repo나 gitlab.example.com/group/project 같이 owner/repo가 아닌 슬래시 포함 소스를 줬습니다. owner/repo 단축형은 GitHub 전용이며 GitHub 이름 규칙을 따라야 합니다. 마켓이 호스팅된 곳에 맞는 형태로 주세요.

• 어느 호스트의 저장소: 전체 clone URL
• 호스팅된 marketplace.json: https:// URL
• 로컬 체크아웃: ./path 또는 절대 경로

예 (세션): /plugin marketplace add https://github.com/anthropics/claude-plugins-official.git.

Invalid git URL

git 주소로 마켓 추가, 플러그인 설치, 업데이트를 하다 Invalid git URL로 실패합니다. Claude Code는 git 실행 전에 모든 git 주소를 검사하며, 지원하지 않는 프로토콜과 git이 보이는 주소와 다른 서버/폴더를 가리키는 것으로 읽을 수 있는 주소를 거부합니다. 주소 뒤의 텍스트가 바꿀 것을 알려 줍니다. is blocked by enterprise policy라면 조직 설정에서 온 것입니다 (Marketplace source is blocked by enterprise policy).

Path does not exist: <path>

marketplace add에 로컬 경로를 줬는데 없습니다. 상대 경로는 현재 디렉터리 기준입니다. 메시지의 해석된 경로를 확인하고 상대 경로의 기준 디렉터리에서 실행하거나 절대 경로를 주세요. Claude Code는 .claude-plugin/marketplace.json이 든 디렉터리 또는 .json 파일 경로를 받습니다. 다른 파일 경로는 File path must point to a .json file (marketplace.json)로 실패.

Marketplace file not found at <path>/.claude-plugin/marketplace.json

clone/다운로드했지만 기대 경로에 marketplace.json이 없습니다. Failed to add marketplace: Marketplace file not found at ...로 보고됩니다. 기본 위치는 저장소 루트의 .claude-plugin/marketplace.json이고 허용 위치는 marketplace reference. 소유자는 그 위치에 파일을 두고 다시 추가, 다른 사람이 호스팅하면 소유자에게 정확한 소스를 문의.

Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name

마켓 marketplace.json의 name이 my-plugin@my-marketplace 같은 플러그인 id의 @ 뒤 부분으로 유효하지 않습니다. 추가를 거부하고 아무것도 등록하지 않습니다.

Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

규칙에 맞는 이름으로 (예: internal-tools) 소유자가 바꾸고 다시 추가합니다. v2.1.295 이전에는 이 예의 추가가 성공으로 보고됐습니다.

Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it

name이 constructor, toString, valueOf 같이 모든 JavaScript 객체가 가진 멤버 이름이라 Claude Code가 예약해 거부합니다 (Reserved names).

Cannot add marketplace "constructor": Claude Code reserves this name and cannot register a marketplace under it. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

settings 파일이 extraKnownMarketplaces로 선언했다면 시작 시 추가 시도가 같은 방식으로 실패하고 /plugin Errors 탭에 나옵니다. 마켓 이름을 바꾸세요. v2.1.296 이전에는 이런 마켓 추가가 이 메시지 대신 내부 오류로 실패했습니다.

SSH authentication failed 또는 HTTPS authentication failed

git 저장소 마켓을 추가/업데이트할 때 Failed to clone marketplace repository: 뒤에 이 줄이 붙어 clone이 실패합니다. 먼저 저장소 자체를 확인하세요 (오타 owner/repo, 존재하지 않는 저장소, 볼 수 없는 비공개 저장소도 이 메시지). 브라우저나 git ls-remote <url>로 존재와 접근을 확인. 저장소가 맞다면 자격 증명이 원인입니다. Claude Code는 git을 대화형 프롬프트 없이 실행하므로 비밀번호·키 passphrase를 물을 수 없습니다 (원 오류에 fatal: Cannot prompt because user interactivity has been disabled 또는 terminal prompts disabled). 비대화로 이미 동작하는 자격 증명만 성공합니다.

• SSH: ssh -T git@<host>가 passphrase 프롬프트 없이 성공해야 하고 호스트가 이미 known_hosts에 있어야 함
• HTTPS: credential helper가 호스트 토큰을 보유해야 함. GitHub는 gh auth login과 gh auth setup-git, 다른 호스트는 personal access token을 git credential helper에 저장. git ls-remote <url>로 테스트

git ls-remote가 프롬프트 없이 성공하면 추가/업데이트를 다시 실행. 성공하면 추가는 Successfully added marketplace: <name>, 업데이트는 셸에서 Successfully updated marketplace: <name>, 세션에서 ✔ Updated 1 marketplace. GitHub owner/repo 소스에서 SSH를 건너뛰려면 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1을 설정하세요. 없으면 github.com SSH 키가 구성된 것으로 보일 때 SSH로 clone하고 SSH clone 실패 시 HTTPS로 폴백합니다. 백그라운드 auto-update가 자격 증명으로 하는 일/못 하는 일은 What background auto-update does with credentials.

SSH host key is not in your known_hosts file

한 번도 접속하지 않은 호스트에 SSH로 마켓을 추가했고 clone이 이 줄과 ssh -T git@<host> 힌트로 실패했습니다. 호스트 키가 바뀐 경우 메시지는 SSH host key has changed와 ssh-keygen -R <host> 힌트입니다. Claude Code는 StrictHostKeyChecking=yes로 clone하므로 수락하지 않은 키를 자동으로 받지 않습니다. 터미널에서 한 번 접속해 fingerprint를 수락한 뒤 재시도하세요.

ssh -T git@github.com

공개 저장소는 SSH를 피하도록 https:// URL로 추가해도 됩니다.

Command 'git' not found or is in an unsafe location

Windows에서 마켓 추가 시 Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory). Claude Code는 PATH에서 git을 찾고 현재 디렉터리에서만 발견된 것은 실행을 거부합니다. (1) git이 PATH에 오도록 Git for Windows 설치, (2) 새 터미널을 열어 갱신된 PATH 적용, (3) git --version이 버전을 출력하는지 확인, (4) marketplace add를 다시 실행.

Git clone timed out after 120s

마켓 추가/업데이트가 Git clone timed out after 120s와 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 설정 힌트로 실패합니다. 마켓 clone과 업데이트용 re-clone의 기본은 120초입니다. 큰 저장소나 느린 연결이면 한도를 올리세요 (밀리초).

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

같은 셸에서 재시도. monorepo라면 claude plugin marketplace add <source> --sparse <paths>로 이름 붙인 디렉터리만 체크아웃합니다.

오프라인에서 마켓 업데이트가 계속 실패

마켓 git 호스트에 닿지 않는 환경에서 세션마다 백그라운드 새로고침 실패가 반복됩니다 (기존 체크아웃은 유지되고 시작은 지연되지 않음). auto-update가 켜진 마켓은 세션마다 새 commit을 백그라운드로 확인하는데, 호스트에 닿지 못하면 마켓을 다시 clone하려 하고 오프라인에서는 그것도 실패합니다. 이 변수는 호스트에 닿지 못할 때 re-clone을 건너뛰고 기존 체크아웃을 유지합니다.

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

$env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

설정하면 .claude-plugin/marketplace.json이 이미 있는 체크아웃에 대해서만 re-clone을 건너뜁니다. clone된 적 없거나 중간에 멈춘 마켓은 여전히 clone을 시도하므로 온라인에서 한 번 추가하세요. 완전 오프라인 배포는 이미지 빌드 시 CLAUDE_CODE_PLUGIN_SEED_DIR로 미리 채우세요 (Seed containers and CI).

GitHub Enterprise Server 호스트에서 마켓 추가 실패

GHES URL로 추가해 정책 오류가 나거나 claude.ai에서 추가해 GitHub 접근 오류가 납니다. 둘 다 GHES 페이지: 정책 오류는 조직이 마켓 소스를 제한해 관리자가 호스트용 hostPattern을 추가해야 한다는 뜻, claude.ai의 GitHub 접근 오류는 본인 GitHub Enterprise 계정이 아직 연결되지 않았다는 뜻.

플러그인 설치

마켓을 추가하고 설치를 실행했는데 메시지와 함께 멈춘 경우입니다. 플러그인이나 마켓을 찾거나 읽거나 신뢰할 수 없을 때 이후 /plugin Errors 탭에 나타나거나 Discover 탭이 비는 관련 메시지도 포함합니다.

Plugin "<name>" not found in marketplace "<marketplace>"

/plugin install <name>@<marketplace> 또는 claude plugin install <name>@<marketplace>를 실행했는데 플러그인 이름이 내 기기의 그 마켓 카탈로그 사본에 없습니다. 마켓을 전혀 추가하지 않았다면 셸의 claude plugin install도 같은 메시지를 냅니다. claude plugin marketplace update <marketplace>가 Marketplace '<marketplace>' not found로 답하면 마켓을 먼저 추가하세요.

• 새로고침 힌트가 있는 경우: 힌트는 Your local copy may be out of date — try claude plugin marketplace update <marketplace> 또는 The marketplace couldn't be refreshed (...). 오프라인 등으로 조회 전에 새로고침하지 않아 카탈로그 사본이 오래됐을 수 있습니다. 마켓 이름으로 새로고침 후 재설치: /plugin marketplace update <marketplace>. claude plugin marketplace update는 Successfully updated marketplace: <name>, /plugin marketplace update는 ✔ Updated 1 marketplace를 출력. 같은 메시지가 반복되면 힌트 없는 경우처럼 이름을 확인. 새로고침이 실행되지 않는 다른 경우는 When Claude Code refreshes a marketplace before an install
• 힌트가 없는 경우: 이름이 가장 유력한 문제. /plugin의 Discover 목록에서 이름을 복사. v2.1.232 이전에는 조회가 빗나간 뒤에야, 그 마켓의 auto-update가 켜져 있을 때만 새로고침했음

Plugin "<name>" not found in any marketplace

@marketplace 없이 /plugin install <name>을 실행했고 등록된 마켓 어디에도 없습니다 (claude plugin install <name>은 Plugin "<name>" not found in any configured marketplace). 마켓 이름이 없으면 claude plugin install은 이미 가진 카탈로그를 새로고침 없이 검색하고, /plugin install은 auto-update가 켜진 마켓만 새로고침합니다. 마켓 이름을 지정하면 조회 전에 새로고침합니다: /plugin install <name>@<marketplace>. 성공하면 세션에서 ✓ Installed <plugin>., claude plugin install은 Successfully installed plugin: <plugin>@<marketplace>. 어느 마켓에 있는지 모르면 /plugin marketplace list와 /plugin의 Discover로 찾으세요.

Plugin '<name>@<marketplace>' is already installed globally

user scope나 managed settings로 이미 설치된 플러그인에 /plugin install을 실행해 Use '/plugin' to manage existing plugins.와 함께 거부됐습니다 (@<marketplace> 없이 입력하면 메시지에서 globally가 빠짐). 이미 모든 프로젝트에서 쓸 수 있으므로 할 일이 없습니다. scope 변경, 활성/비활성, 구성은 /plugin의 Installed에서. project나 local scope에만 설치된 플러그인은 이 메시지를 내지 않고 user scope에도 설치할 수 있습니다. 셸의 claude plugin install은 다른 메시지를 냅니다: 대상 scope에 이미 설치돼 있으면 Plugin "<name>@<marketplace>" is already installed (scope: user)를 출력하고 exit 0, 캐시 디렉터리가 없으면 같은 명령이 다시 내려받습니다.

"<plugin>" was not installed: it would share its folder with "<other>"

claude plugin install, /plugin, 세션의 설치 제안으로 설치했는데 이 줄(또는 would share its saved data with)로 거부됐습니다. 거부된 플러그인 id와 설치된 플러그인 id가 디스크의 같은 폴더로 매핑됩니다 (.와 @를 -로 쓰면 같음; macOS·Windows에서는 대소문자만 다른 id도 같은 폴더). 둘을 설치하면 한쪽 파일이 다른 쪽 폴더에 들어가므로 거부하고 설치된 플러그인이 파일을 유지합니다.

• 다른 플러그인이 설치된 경우: Only one of the two can be installed.와 다른 플러그인을 제거하는 claude plugin uninstall 명령(또는 /plugin의 제거 단계)이 나옴. 실행 후 다시 설치. 제거가 지우는/남기는 것은 What an uninstall deletes and keeps
• 한 설치에 두 id가 함께 오는 경우 (플러그인과 의존성 등): 설치 순서로 해결 불가. 두 플러그인을 나열한 마켓 유지보수자만 하나를 rename해 고칠 수 있음. 서로 다른 마켓이면 어느 쪽 유지보수자든 가능

This plugin uses a source type your Claude Code version does not support

마켓 항목이 이 버전의 Claude Code가 가져올 수 없는 소스 타입을 씁니다. Update Claude Code and try again. Claude Code를 업데이트한 뒤 재시도. 소스 타입은 marketplace reference.

Plugin archive integrity check failed

zip 아카이브로 배포되는 플러그인이 이 줄과 The archive was not installed.로 거부됐습니다. 마켓 항목이 sha256 고정이 있는 archive 소스를 쓰는데 내려받은 파일의 digest가 맞지 않습니다.

Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

• 게시자: URL이 서빙하는 정확한 파일의 digest를 다시 계산해 마켓 항목의 sha256 갱신. shasum -a 256 my-plugin.zip, PowerShell은 Get-FileHash -Algorithm SHA256 my-plugin.zip
• 설치자: 항목이 고쳐졌을 수 있으니 세션에서 /plugin marketplace update <name>으로 카탈로그를 새로고침한 뒤 재시도. 새로고침 후에도 digest가 다르면 설치 전에 마켓 소유자에게 어떤 파일을 고정했는지 문의

An npm plugin source must name a registry package

npm 소스 마켓 항목의 플러그인이 설치·업데이트·로드에 실패하고 메시지에 이 문장이 있습니다. Claude Code가 가져오기 전에 항목의 package 값을 검사해 거부했고 메시지가 값과 이유를 명시합니다.

"github:acme/formatter" was not installed: it is not an http or https link. An npm plugin source must name a registry package (name or name@version) or link to a tarball file. For a plugin in a git repository, use a "github", "url" or "git-subdir" source.

마켓 소유자가 항목을 바꿔야 합니다: package를 npm plugin source reference가 받는 값으로 바꾸거나 github, url, git-subdir 소스로 전환. 소유자가 아니면 마켓 소유자에게 보고.

Marketplace "<name>" is registered from an untrusted source

이전에 추가한 마켓과 그 플러그인이 로드되지 않습니다 (/plugin Errors 탭이나 다음 새로고침에 나타남). 마켓이 공식 Anthropic 마켓용으로 예약된 이름으로 등록돼 있는데 등록된 소스가 anthropics GitHub 저장소가 아닙니다. 예약 이름은 마켓이 로드·새로고침될 때마다 재검사됩니다.

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

• 사용자: 셸에서 claude plugin marketplace remove <name> 후 공식 github.com/anthropics 저장소에서 다시 추가
• 이 이름이 예약되기 전부터 쓴 서드파티 마켓 게시자: 이름을 바꾸고 사용자에게 내 소스에서 다시 추가하도록 안내

v2.1.205 이전에는 마켓을 추가할 때만 이름을 검사해, 이름이 예약되기 전에 등록된 항목은 계속 로드됐습니다.

Marketplace "<name>" is added but ignored

마켓이 ~/.claude/plugins/known_marketplaces.json에 항목이 있지만 Claude Code가 그 파일을 읽을 때마다 실행하는 검사에 실패해 마켓과 그 플러그인이 로드되지 않습니다. 셸에서 claude plugin list가 영향받는 각 플러그인을 이유와 해결을 명시한 줄로 보고합니다.

Marketplace team-tools is added but ignored. Its location is on a network drive, has "." or ".." in its path, or couldn't be checked. Re-add the marketplace (one added from a folder or file must be re-added from a copy on this computer), or, to trust a folder on a network drive, declare it under extraKnownMarketplaces in user or managed settings.

세션에서는 /plugin Errors 탭이 마켓 이름을 따옴표로 감싸고 이유 뒤에서 줄을 끝내며 아래 줄에 해결을 보여 줍니다. is added but ignored 뒤 문장이 실패한 검사를 명시합니다.

• Its location is on a network drive, has "." or ".." in its path, or couldn't be checked (또는 The folder or file it was added from에 대한 같은 문장): 마켓 디렉터리나 추가한 로컬 경로가 네트워크 위치에 있거나 ./.. 세그먼트가 있거나 검사할 수 없음
• Its git URL can't be used: <reason> 또는 Its URL can't be read as an https:// or http:// address: 기록된 소스 URL이 Claude Code가 clone/fetch를 거부하는 것
• Its source doesn't match its extraKnownMarketplaces entry in user or managed settings: 같은 이름의 extraKnownMarketplaces 선언과 항목이 맞지 않음

이유 자리에 (see the debug log)가 오면 예약 이름의 다른 철자 같은 마켓 이름을 거부한 것이며 debug log가 항목을 명시합니다. 할 일:

• 메시지의 해결을 따름. 셸에서 claude plugin marketplace remove <name> 후 지원되는 소스나 로컬 경로에서 다시 추가하고 플러그인을 재설치 (remove가 플러그인을 제거함). remove 명령은 ignored 항목에도 동작
• 네트워크 위치의 마켓을 유지하려면 user 또는 managed settings의 extraKnownMarketplaces에 선언. 저장소의 .claude/settings.json이나 .claude/settings.local.json 선언은 인정되지 않음
• settings 선언과 소스가 다르면 선언된 소스에서 다시 추가하거나 선언을 변경. claude plugin marketplace add도 같은 불일치를 거부 (아래 항목)
• 거부된 이름은 마켓을 remove (줄이 Remove it: 뒤에 명령을 주면 그 명령). 같은 이름으로 다시 추가하면 다시 거부

v2.1.286 이전에는 이유와 무관하게 claude plugin list가 Marketplace <name> not found, /plugin Errors 탭이 Marketplace "<name>" is registered but was refused (see the debug log)로 보고했고 이유는 debug log에만 있었습니다. v2.1.286에서는 이유·해결 문장 표현이 달랐습니다 (예: Its recorded location is network-shaped or unclassifiable (never probed)).

Plugin <name> has a corrupt manifest file 또는 has an invalid manifest file

플러그인을 가져왔지만 .claude-plugin/plugin.json을 읽지 못했습니다. 셸에서 이 줄의 <name>은 임시 디렉터리 이름일 수 있고 실제 이름은 Failed to install plugin "<name>@<marketplace>" 접두에 있습니다.

• corrupt manifest file + JSON parse error:: 파일이 유효한 JSON이 아님
• invalid manifest file + Validation errors:: 파싱은 되지만 스키마 실패 (예: 필수 필드 누락의 name: Invalid input)

claude plugin install은 둘 다 Failed to install plugin "<name>@<marketplace>":로 보고하고 exit code 1. 작성자가 고쳐야 하며 그때까지 설치할 수 없습니다. 본인이면 셸에서 claude plugin validate <plugin-directory>로 문제 경로가 포함된 같은 오류를 보고 파일을 고치고, 아니면 마켓 소유자에게 보고.

Plugin directory not found at path: <path>

마켓이 ./plugins/my-plugin 같은 상대 경로로 나열한 활성 플러그인에 대해 마켓 안 그 경로에 디렉터리가 없을 때 /plugin Errors 탭에 나옵니다. 마켓을 유지한다면 항목의 source 경로를 고치거나 폴더를 복원하고, 아니면 소유자에게 보고. Marketplace directory not found at path: <path>는 마켓 자체 디렉터리가 없다는 뜻입니다 (로컬 경로로 추가한 마켓의 디렉터리가 이동/삭제됨). 복원하거나 마켓을 remove하고 새 위치에서 다시 추가.

No plugins available 또는 No marketplaces configured

/plugin의 Discover 탭이 비었거나 claude plugin marketplace list가 No marketplaces configured를 출력합니다. 등록된 마켓이 없습니다. 세션에서 공식 마켓을 추가하세요.

/plugin marketplace add anthropics/claude-plugins-official

Successfully added marketplace: claude-plugins-official이 나오고 Discover가 플러그인을 나열합니다. 추가할 수 있는 다른 마켓은 Anthropic marketplaces.

Marketplace "<name>" is already added from a different source

세션이나 셸에서 install 명령의 --marketplace <source>로 새 마켓 소스를 줬는데, 그 소스에서 가져온 카탈로그가 이미 다른 소스로 추가한 마켓과 같은 이름입니다. Claude Code는 교체하지 않고 기존 마켓을 유지하며 플러그인은 설치되지 않습니다.

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

• 이미 추가한 마켓 사용: /plugin install <plugin>@<name>
• 새 소스 사용: /plugin marketplace remove <name> 후 설치 재시도

Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings

추가한 마켓의 marketplace.json name이 user 또는 managed settings의 extraKnownMarketplaces 항목에 이미 있는데 준 소스가 그 항목의 소스와 다릅니다. 추가를 거부하고 아무것도 등록하지 않습니다. 두 소스는 타입과 모든 필드 값이 같아야 일치합니다. 내가 주지 않은 ref가 항목에 있으면 다른 것이고, github 항목에 저장소를 https://github.com/ URL로 주면 git 소스로 기록되므로 다른 것입니다.

• 선언된 소스 사용: Claude Code가 settings에 선언된 마켓을 스스로 등록하므로 먼저 세션에서 /plugin marketplace list. 이름이 보이면 이미 등록됨. 없으면 항목이 쓴 방식 그대로 소스를 입력. 예: 항목의 source 객체가 { "source": "github", "repo": "acme-corp/claude-plugins", "ref": "v1.2.0" }이면 /plugin marketplace add acme-corp/claude-plugins#v1.2.0
• 새 소스 사용: extraKnownMarketplaces 항목을 수정/제거하고 다시 추가. managed settings가 선언했으면 관리자에게 문의

v2.1.287 이전에는 Cannot add marketplace "<name>": its network source differs from the one declared for it in settings (kind, target, or a fetch-shaping field such as headers / ref / path / sparsePaths)였습니다.

Failed to install: <plugin> (<reason>)

/plugin 메뉴에서 플러그인을 선택해 설치했지만 아무것도 설치되지 않고 실패 요약과 함께 메뉴가 닫혔습니다. git clone 실패 출력 같은 일부 이유는 첫 줄만 표시되며, 줄인 경우 요약이 Installing a plugin from its details (Enter) in /plugin shows its full error.로 끝납니다. 괄호 안 이유가 명시한 것을 고치고, 줄었다면 /plugin의 Discover 탭에서 플러그인을 선택하고 Enter로 상세에서 설치하세요. 거기서도 실패하면 상세 화면이 전체 오류를 보여줍니다.

Could not move the new copy of this plugin version into <path>

플러그인 설치는 새 파일 사본을 내려받아 플러그인 캐시의 그 버전 폴더로 옮깁니다. 이동이 실패했다는 뜻이며 보통 설치 중 다른 프로그램이 폴더를 사용했기 때문입니다. 파일시스템 코드가 괄호에 나옵니다.

Could not move the new copy of this plugin version into /home/user/.claude/plugins/cache/acme-tools/formatter/1.2.0: the new copy or the version folder stayed busy while the install ran (ENOTEMPTY) — usually a scanner still reading the freshly downloaded files, another program using that folder, or another process re-creating it. The previously installed copy was moved back. Run the install again once other Claude Code sessions or programs using that folder have finished.

이전에 설치된 사본에 일어난 일이 플러그인이 아직 동작하는지 알려 줍니다.

• The previously installed copy was moved back: 기존 버전은 여전히 설치됨
• had to be removed first, was not moved back, could not be moved back: 설치가 성공할 때까지 그 플러그인 버전은 설치되지 않음
• 그런 문장 없음: 이전 사본이 없어 아직 설치 안 됨

Windows에서 다른 프로그램이 설치된 사본 자체를 잡고 있으면 그 사본이 could not be replaced, It was not replaced and the new copy was discarded라고 해서 기존 버전이 유지됩니다. Left on disk 목록은 캐시 안의 따로 치워 둔 폴더를 명시하며 이후 그 버전 설치나 플러그인 캐시 정리가 제거하므로 지울 필요가 없습니다. 해결: ~/.claude/plugins/cache 아래 그 플러그인 폴더를 쓰는 다른 Claude Code 세션·에디터·터미널을 닫고 재설치. 메시지가 캐시 폴더 권한 확인을 말하면 명시된 폴더의 쓰기 권한을 복원하고 디스크 공간을 확보한 뒤 재설치.

의존성 오류

의존성을 선언한 플러그인은 의존성을 만족할 수 없을 때 설치에 실패하거나 설치되지만 비활성으로 남을 수 있습니다. 설치 시에는 거부가 설치 오류 메시지로, 로드 시에는 claude plugin list와 /plugin Errors 탭에 나타나며 해결할 때까지 영향받은 플러그인을 비활성으로 유지합니다. 작성자 선언은 Plugin dependencies.

메시지	의미	해결
Dependency "<dep>" is not installed	선언된 의존성이 설치되지 않음	셸에서 claude plugin install <dep>@<marketplace> 또는 플러그인 제거. 의존성의 마켓이 아직 등록되지 않았다면 추가 후 세션에서 /reload-plugins (해결 가능한 누락 의존성을 설치)
is not installed 메시지 안의 "<name>@synced" is loaded from your claude.ai account but meets a marketplace dependency only for other claude.ai plugins	의존성이 마켓을 지목하는데 그 이름의 플러그인이 claude.ai 계정에서 로드됨. 의존성을 선언한 플러그인이 claude.ai에서 로드되지 않으므로 claude.ai 플러그인이 충족하지 못함	셸에서 claude plugin install <dep>@<marketplace>로 마켓에서 의존성 설치
Dependency "<dep>" is disabled	의존성이 설치됐지만 꺼져 있음	의존성을 활성화하거나 필요로 하는 플러그인 제거
Requires "<dep>" <range>, installed <version>	설치된 의존성 버전이 선언 범위 밖	범위 안으로 의존성 업데이트 또는 플러그인 제거
<Plugin or Dependency> "<name>" has conflicting version requirements	고정하는 모든 범위를 만족하는 버전이 없음. 메시지가 범위를 나열	충돌 플러그인 중 하나를 제거·업데이트하거나 업스트림 작성자에게 제약 완화 요청
... has version requirements too complex to intersect 또는 has an invalid version requirement	범위가 유효한 semver가 아니거나 합친 범위를 교집합할 수 없음	잘못된 범위를 고치거나 긴 || 체인을 단순화
... has no git tag satisfying <range>	의존성 저장소에 범위 안의 <name>--v* 태그가 없음	업스트림이 그 규칙으로 릴리스를 태그하는지 확인하거나 범위를 완화
Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist	의존성이 다른 마켓에 있고 크로스 마켓 해석은 기본 꺼짐	플러그인을 설치하는 것과 같은 scope로 셸에서 claude plugin install <dep>@<marketplace> (+ --scope) 설치 후 재시도

프로그램으로 보려면 셸에서 claude plugin list --json. 문제가 있는 플러그인은 메시지의 errors 필드와 각각 type을 가진 errorDetails 필드를 가집니다. 첫 세 행은 dependency-unsatisfied, 네 번째는 dependency-version-unsatisfied입니다.

설치 후 미동작

설치는 성공했지만 skill, hook, 서버가 아무것도 하지 않는 경우입니다.

플러그인이 보이지 않거나 skill이 나타나지 않음

/를 입력해도 skill이 안 보이거나 Claude에게 쓰라고 해도 아무 일이 없습니다. 바꾸기 전에 상태를 확인하세요.

1. 설치·활성화 확인: /plugin의 Installed에서 플러그인이 나열되고 활성인지 확인. 셸의 claude plugin list는 각 플러그인의 버전, scope, Status: ✔ enabled를 출력
2. Errors 탭 읽기: 같은 패널의 Errors 탭. 각 항목은 메시지와 안내 줄 쌍. 이 절 대부분의 메시지가 여기서 나옴
3. 이 세션 중 설치했다면 리로드: 설치됐고 오류가 없는데 이 세션 중 설치했다면 /reload-plugins. 플러그인, skill, agent, hook, 서버 개수와 함께 Reloaded:를 출력하고 실패가 있으면 N errors during load. Run /plugin for details. 추가

오류 없이 로드되는데 skill이 없으면: 직접 만드는 플러그인은 Plugin loads but its skills are missing, 남이 게시한 플러그인은 /plugin의 Installed에서 상세 pane을 열어 구성을 확인 (거기 skill이 없으면 /에 나올 것도 없음).

Run /reload-plugins to apply.

/plugin 설치 요약이 Plugin is now active. 대신 Run /reload-plugins to apply.로 끝났습니다. 동시에 프롬프트 위에 Plugins changed. Run /reload-plugins to activate. 알림이 나올 수 있습니다. 활성화가 프롬프트 캐시를 무효화하거나 활성화 시도가 실패해서 Claude Code가 설치 중에 활성화하지 않았습니다. 명령을 입력할 필요 없이 패널이 닫히고 Claude Code가 /reload-plugins를 대신 실행하거나 스트리밍 중인 응답이 끝날 때까지 대기시킵니다. 리로드가 출력하는 것을 읽으세요.

• 개수와 함께 Reloaded:: 플러그인이 활성. 실패가 있으면 N errors during load. Run /plugin for details. 추가
• This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.: 리로드가 플러그인 MCP 서버나 LSP 도구를 더하거나 빼 프롬프트 캐시를 무효화. LSP는 This reload adds the LSP tool 또는 This reload removes the LSP tool로 시작. 그래도 활성화하려면 --force, 아니면 새 세션 시작

v2.1.268 이전에는 설치 중 활성화되지 않은 설치가 /reload-plugins를 직접 실행할 때까지 대기 상태였습니다. v2.1.246 이전에는 요약의 skill 개수가 플러그인의 commands/ 항목만 세어 SKILL.md skill이 로드돼도 0 skills로 보고될 수 있었습니다.

The packages it lists are not installed 또는 were not installed, because ...

의존성 설치가 node_modules를 남기지 않은 플러그인에 /plugin과 claude plugin list가 이 노트를 표시합니다. 플러그인은 로드되지만 없는 패키지가 필요한 부분은 동작하지 않을 수 있습니다.

• are not installed: 이 플러그인의 설치를 실행할 수 있지만 실패·타임아웃 등으로 끝나지 않음. 셸에서 노트가 주는 claude plugin update 명령을 실행하거나 /plugin에서 업데이트해 재시도: claude plugin update formatter@my-marketplace. 재시도가 실패하면 출력이 원인을 줌. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC가 설정된 동안은 claude plugin update와 /plugin이 재시도를 건너뛰고 플러그인이 최신이라고 보고
• were not installed, because ...: 이 플러그인의 설치를 실행할 수 없고 노트가 이유를 명시 (Yarn, pnpm, bun.lockb lockfile, 또는 이 컴퓨터에 없는 패키지 관리자의 lockfile). 이유가 유지되는 동안 업데이트해도 패키지가 설치되지 않음. lockfile이 이유면 작성자가 교체해야 하고, 패키지 관리자가 없으면 설치 후 업데이트

Plugin "<name>" not cached at <path>

Errors 탭이 안내 Run /plugin to refresh the plugin cache와 함께 이 줄을 보여줍니다. 플러그인에 설치 기록이 있지만 기록이 가리키는 디렉터리가 없습니다 (예: 캐시를 지움). 셸에서 재설치하세요. claude plugin install <name>@<marketplace>는 기록은 있지만 설치 디렉터리가 없는 플러그인을 다시 내려받습니다. 이후 세션에서 /reload-plugins를 실행하면 Errors 탭 항목이 사라지고 Installed에 돌아옵니다.

installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read

나타나는 형태:

• claude plugin list: Note:로 출력
• claude plugin install, uninstall, update: Plugin "<name>" was not installed:, Plugin "<name>" was not uninstalled:, Plugin "<name>" was not updated: 뒤에 같은 텍스트로 거부
• 이 세 명령의 --json: 결과 줄에 같은 message와 failureCode: "install_records_unreadable"
• 여러 기록: holds records under
• 파일 전체가 이 버전이 모르는 형식: 대신 installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know

installed_plugins.json의 명시된 기록은 유효한 플러그인 id 아래 유효한 JSON이지만 필드를 이 버전이 파싱하지 못합니다. 보통 다른(더 새로운) 버전의 Claude Code가 썼습니다. 기록이 있는 동안 이 버전은 파일을 다시 쓰지 않으므로 기록이 사라지지 않습니다. 순서대로: (1) claude update, (2) 업데이트할 수 없으면 기록을 쓴 Claude Code 버전으로 명시된 플러그인 제거, (3) 둘 다 안 되면 installed_plugins.json에서 기록을 손으로 삭제한 뒤 Claude Code를 재시작하거나 /reload-plugins.

installed_plugins.json could not be read and was rebuilt

claude plugin list가 installed_plugins.json 옆에 installed_plugins.unreadable.<date>.<hash>.kept 파일이 있는 동안 그 경로와 함께 이 노트를 출력합니다. 유효한 JSON이 아니거나 플러그인 목록이 아닌 installed_plugins.json은 무엇을 설치했는지 말해 줄 수 없습니다. .kept 파일을 열어 옛 파일이 기록한 것을 보고 빠진 플러그인을 재설치하세요. Claude Code는 이 파일을 다시 읽지 않으며 cleanupPeriodDays 일정으로 사라집니다.

install records under names that no version of Claude Code can use were removed from installed_plugins.json

claude plugin list가 installed_plugins.json 옆에 installed_plugins.set-aside.<date>.<hash>.json 사본이 있는 동안 그 경로와 함께 이 노트를 출력하며 Nothing needs doing about these copies.로 끝납니다. installed_plugins.json의 기록이 유효한 플러그인 id가 아닌 키 아래에 있어 어느 버전도 쓸 수 없습니다. 파일의 나머지는 정상 로드됩니다. Claude Code가 쓸 수 없는 기록을 .set-aside 파일에 복사하고 목록에서 뺍니다. 사본은 다시 읽히지 않고 cleanupPeriodDays 일정으로 사라집니다.

does not load (...), so Claude Code ignores the whole file

명령은 성공했습니다. 경고가 지목한 settings 파일에 오류가 있어 Claude Code가 명령이 쓴 것을 포함해 파일 전체를 무시합니다. 오류를 고칠 때까지입니다. Claude Code가 받지 않는 값은 Fix a broken settings file을 보고, 변경이 파일에 없으면 명령을 다시 실행하세요. 경고는 셸의 claude plugin install, enable, disable, claude plugin marketplace add의 성공 줄 뒤에 붙습니다.

⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.

괄호 안 텍스트가 오류를 명시합니다.

• its "<key>" is not valid: 인용된 설정이 Claude Code가 받지 않는 값을 가짐. 받는 값은 settings reference. 둘 이상 실패하면 첫 설정을 명시하고 나머지는 개수로 (its "permissions" and 1 other value are not valid)
• it is not a JSON object: 파일 최상위가 배열 등 JSON 객체가 아님

Disabled in ~/.claude/settings.json but still loads

~/.claude/settings.json에서 플러그인을 false로 설정했는데 claude plugin list나 /plugin의 행이 이를 활성화하는 소스(예: — project settings enable it, which overrides your user setting)와 함께 이 메시지를 표시합니다. 더 높은 우선순위 소스의 true가 user 설정을 덮어씁니다. 프로젝트가 켠 플러그인을 내 기기에서 끄려면 프로젝트 파일보다 우선순위가 높은 .claude/settings.local.json에서 id를 false로 설정하세요. 메시지가 지목할 수 있는 다른 소스는 Disabled in user settings but still loads. claude plugin list가 대신 required by your org로 표시하면 settings 파일과 무관합니다. 조직이 claude.ai에서 sync된 플러그인을 필수로 표시했고 이전에 비활성했어도 로드됩니다 (Plugins synced from claude.ai).

Plugin "<name>" is enabled in project settings but isn't installed here

프로젝트 .claude/settings.json이 활성화한 플러그인에 Errors 탭이 안내 Run claude plugin install <name>@<marketplace> --scope project to install it for this project와 함께 이 줄을 보여줍니다. 저장소 settings는 여는 모든 사람에게 플러그인을 활성화할 수 있지만 설치하지는 않습니다. GitHub 저장소나 npm 패키지 같은 외부 소스의 플러그인은 직접 설치하기 전에는 내려받지 않습니다. 안내 줄의 명령을 셸에서 실행하고 리로드하세요.

claude plugin install <name>@<marketplace> --scope project

세션에서 /reload-plugins 후 Errors 탭 항목이 사라지고 Installed에 나열됩니다. 조직이 미리 설치한다면 managed settings로 합니다 (Pre-install and require plugins).

Windows에서 plugin uninstall 후에도 플러그인이 남음

Windows에서 project나 local scope로 claude plugin uninstall이 성공을 보고하지만 claude plugin list나 /plugin에 여전히 나옵니다. installed_plugins.json에 프로젝트 폴더에 대한 플러그인 설치 기록이 폴더 경로 철자만 다른 둘이 있고 한 번의 uninstall이 하나만 제거합니다. 확인하려면 셸에서 claude plugin list --json. 남은 행의 projectPath가 uninstall을 실행한 곳과 다르게 철자됩니다 (C:\work\app 대 c:\work\app). 같은 폴더에서 같은 --scope로 같은 uninstall 명령을 다시 실행하세요. 두 번째 실행은 자기 철자 아래 기록이 없으므로 다른 철자의 기록을 제거합니다. project scope 설치라면:

claude plugin uninstall <name>@<marketplace> --scope project

이후 claude plugin list --json으로 행이 사라졌는지 확인. v2.1.295 이전에는 두 번째 실행이 Plugin "<name>" is not installed in project scope로 실패하므로 claude update 후 uninstall을 다시 실행하세요.

git 저장소에서 설치한 플러그인의 버전이 unknown

claude plugin list의 Version: unknown은 Claude Code가 git 소스 플러그인의 버전으로 쓰는 commit을 읽지 못했다는 뜻일 수 있습니다. 플러그인이 자체 저장소를 갖거나 git 호스팅 마켓 안에 있을 수 있습니다. 셸에서 실행하고 formatter@my-marketplace는 claude plugin list의 name@marketplace로 바꾸세요.

1. Claude Code 업데이트: commit을 읽을 수 있는 형식으로 clone하는 v2.1.302 이상으로 업데이트: claude update
2. 마켓 업데이트: 마켓 저장소 안 플러그인의 commit을 가진 마켓 사본 갱신: claude plugin marketplace update my-marketplace
3. 플러그인 업데이트: 기록된 버전을 다시 씀: claude plugin update formatter@my-marketplace
4. 버전 확인: claude plugin list의 Version:이 12자 commit ID 같은 값인지 확인

claude plugin update는 실행당 한 scope의 블록만 바꿉니다. 여전히 unknown인 블록은 그 블록의 Scope: 값으로 다시 실행: claude plugin update formatter@my-marketplace --scope project. 다시 실행해도 unknown이면 Get more help.

Failed to load hooks from <path>와 동작하지 않는 hook

플러그인 hook이 실행되지 않거나 동작을 막습니다. Errors 탭에 로드 실패가 나오거나, hook이 로드되고 transcript에 <Event> hook error 알림/차단 오류가 나오거나, hook이 오류 없이 로드되지만 발동하지 않습니다.

hook 로드 실패 (Errors 탭):

• Failed to load hooks from <path>: <reason>: hooks/hooks.json이 유효한 JSON이 아니거나 hooks 스키마 실패. 이유가 파싱/검증 오류를 명시. 파일을 고치세요. 게시 전 hooks/hooks.json의 JSON 구문 문제는 셸에서 claude plugin validate <plugin-directory>로 잡음
• hooks path not found: <path>: 매니페스트의 hooks 필드가 플러그인 루트 기준 그 경로에 없는 파일을 지목. 경로를 고치거나 파일 추가
• hooks path escapes plugin directory: <path>: Path escapes plugin directory

transcript의 hook error 알림: ... hook error: Failed with non-blocking status code: <stderr> 형태는 hook이 실행됐고 명령이 실패했다는 뜻입니다. 예: Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found는 Claude Code가 띄운 셸이 node를 찾지 못했다는 뜻. 설치하거나 claude를 시작하는 터미널의 PATH에 두세요. stderr에 플러그인 경로가 공백에서 잘려 보이면 hook의 shell-form 명령이 ${CLAUDE_PLUGIN_ROOT}를 따옴표 밖에서 쓰고 설치 경로에 공백이 있는 것입니다. 변수를 큰따옴표로 감싸거나 exec form을 쓰세요. 따옴표 없는 변수는 플러그인 디렉터리에 claude plugin validate를 실행해 quoting 경고로 찾습니다. 알림이 Failed to run: Plugin directory does not exist: <path>면 Plugin directory does not exist. 다른 오류는 플러그인 디렉터리에서 hook 명령을 직접 실행해 전체 출력을 보거나 debug logging으로 전체 stderr를 캡처.

플러그인 hook이 도구 호출이나 프롬프트를 막음: exit code 2인 hook은 실행 대상 동작을 막습니다. 플러그인 hook이 이렇게 막고 stderr가 차단 메시지이면 오류가 This hook comes from the <plugin> plugin.으로 끝나 어느 플러그인을 비활성/수정할지 알 수 있습니다 (v2.1.281 이전에는 플러그인을 명시하지 않음). 메시지에 플러그인 경로가 공백에서 잘려 보이면 위의 따옴표 없는 ${CLAUDE_PLUGIN_ROOT} 수정을 적용.

hook이 로드되지만 발동하지 않음: 먼저 세션에서 /plugin을 실행해 플러그인 상세를 엽니다. Its hooks.json hooks do not run으로 시작하는 노트가 있으면 같은 이름의 다른 활성 플러그인이 대신 hook을 등록한 것이며 어느 사본인지와 전환 방법은 Hooks when two enabled plugins share a name. 그 외:

1. 이벤트 이름 확인: 대소문자 구분. 정확히 일치하는지 (예: PostToolUse)
2. matcher 확인: hook의 matcher가 도구 이름과 맞는지
3. 의도적으로 이벤트 발생: PostToolUse hook이면 Claude에게 파일 편집을 시킴
4. debug log 읽기: debug log가 어느 hook이 맞았는지 기록. 실행된 hook은 exit code와 함께 나옴

Plugin directory does not exist: <path>

메시지가 재설치를 말해도 먼저 Claude Code 프롬프트에서 /reload-plugins를 실행하세요. 세션이 플러그인의 hook을 로드한 디렉터리가 디스크에서 사라지면 hook이 Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)로 실패하고 실행되지 않습니다. Plugin directory not found at path: <path>와는 다릅니다. 리로드는 현재 디렉터리에서 hook을 로드합니다. 실패는 hook 이벤트·명령당 세션에 한 번만 표시되므로 hook이 조용해졌다고 수정 확인이 되지 않습니다. 대신 리로드 출력을 읽으세요.

• 오류 줄 없는 Reloaded:: hook이 더는 없는 디렉터리를 가리키지 않음
• N errors during load. Run /plugin for details.: /plugin의 Errors 탭을 열어 표시된 메시지의 항목을 따름
• Run /reload-plugins --force to apply.로 끝나는 줄: 아무것도 리로드되지 않았고 hook이 계속 실패. Claude Code 프롬프트에서 /reload-plugins --force

Invalid MCP server config for "<server>"와 시작하지 않는 MCP 서버

플러그인이 MCP 서버를 번들하는데 Errors 탭이 Invalid MCP server config for "<server>": <error>를 보여주거나 서버가 나열되지만 /mcp에서 연결된 적이 없습니다.

Invalid MCP server config for "<server>": <error>: 서버 구성은 스키마 검사를 통과하지만 Claude Code가 이 세션에서 해석할 수 없습니다. 콜론 뒤 텍스트가 원인과 해결을 정합니다.

• Missing environment variables: <names>: Claude Code를 시작하는 셸에 그 변수를 설정하고 새 세션 시작
• URL is unset or invalid: URL이 쓰는 ${user_config.*} 옵션이 설정되지 않음. /plugin configure <plugin>으로 설정
• has an invalid MCP url 또는 headersHelper for MCP server '<server>' references ${user_config.*}: 플러그인 자체 구성의 문제. 플러그인 MCP 구성의 url이나 headersHelper를 고치거나 내 플러그인이 아니면 작성자에게 보고. headersHelper 경우는 plugin command references user_config에 별도 항목

Bundled MCP server "<name>" was not started: it needs configuration: 플러그인이 user_config를 선언한 MCPB 번들로 서버를 포함하는데 필수 설정에 저장된 값이 없거나 저장된 값이 번들 자체 검증에 실패해 Claude Code가 서버 시작을 건너뜁니다. 플러그인의 나머지는 동작합니다. /plugin의 Installed 탭에서 플러그인을 선택하고 Configure로 값을 제공하세요. 저장하면 /plugin이 Configuration saved.를 표시하고 닫히며 Manage installed plugins에 설명된 대로 Claude Code가 플러그인을 리로드합니다. 리로드가 적용되면 서버가 시작됩니다. v2.1.285 이전에는 이 줄 없이 서버를 건너뛰었습니다.

서버가 구성됐지만 연결되지 않음: /mcp로 서버 상태를 봅니다 (정상이면 연결됨으로 나열). 서버가 시작 중 출력한 오류는 claude --debug를 실행해 ~/.claude/debug/<session-id>.txt의 로그를 엽니다. --debug는 터미널에 출력하지 않습니다. 스키마에 실패한 .mcp.json 서버 항목은 Errors 탭에 나타나지 않고 Claude Code가 서버를 버리며 Invalid MCP server config for <server> in <path>를 그 debug log에만 기록합니다. 플러그인을 로드하지 않고 항목을 찾으려면 플러그인 디렉터리에 셸에서 claude plugin validate를 실행하면 오류로 보고합니다. v2.1.281 이전에는 claude plugin validate가 .mcp.json을 검사하지 않았습니다.

--plugin-dir에서는 서버가 동작하지만 설치 후 실패: 작성자가 소스 디렉터리를 --plugin-dir로 로드하면 서버가 시작되지만 설치하면 실패합니다. Claude Code는 설치된 플러그인을 캐시로 복사하므로 소스 디렉터리에서만 동작하는 경로가 깨집니다. 플러그인 내부 경로는 ${CLAUDE_PLUGIN_ROOT}로 쓰세요. 플러그인 디렉터리 밖을 가리키는 경로는 Files the plugin references outside its directory aren't found.

언어 서버가 시작하지 않거나 메모리를 많이 쓰거나 잘못된 진단을 보고

code intelligence 플러그인을 설치했는데 Claude가 진단을 보지 못하거나 언어 서버가 메모리를 많이 쓰거나 실제가 아닌 오류를 보고합니다.

• 언어 서버가 시작하지 않음: 플러그인은 별도로 설치하는 language server 바이너리에 연결하며 Claude Code는 PATH의 명령 이름으로 띄웁니다. /plugin Errors 탭이 Executable not found in $PATH: "<binary>" 같은 이유와 함께 실패를 보여주고 claude --debug는 LSP server <name> failed to start: <reason>로 로그합니다. 바이너리를 설치하고 claude를 시작하는 터미널의 PATH에 있는지 확인 (예: which typescript-language-server). 새 세션 시작
• 메모리 과다: rust-analyzer, pyright 같은 서버는 전체 프로젝트를 색인합니다. 세션에서 /plugin disable <plugin>으로 끄고 Claude의 내장 검색 도구에 의존
• monorepo의 잘못된 진단: 워크스페이스에 맞게 구성되지 않은 서버가 내부 패키지의 해석 불가 import를 보고할 수 있음. Claude Code 쪽에서 고칠 것은 없고 진단이 Claude의 코드 편집을 막지 않음

플러그인 개발

--plugin-dir로 로드하거나 로컬 마켓에서 설치하며 개발할 때의 실패입니다. 변경 후 점검은 Test and debug. 사용자에게도 닿는 두 실패는 설치 후 미동작에 있습니다: 동작하지 않는 hook, 시작하지 않는 MCP 서버.

commands path not found: <path>

Errors 탭이 안내 Check that the path in your manifest or marketplace config is correct와 함께 commands path not found: <absolute path>를 보여줍니다. skills, agents, hooks도 같은 메시지입니다. Claude Code가 plugin.json이나 마켓 항목의 경로를 플러그인 루트 기준으로 해석했는데 아무것도 없습니다. 메시지의 경로가 확인한 절대 경로이므로 디스크와 비교하세요. 경로를 고치거나 디렉터리를 만들고 /reload-plugins. 매니페스트 경로는 플러그인 루트 기준이고 ./로 시작합니다. 플러그인 루트 밖으로 해석되는 경로는 대신 <component> path escapes plugin directory로 보고되고 버려집니다. (v2.1.299 이전에는 claude.ai에서 sync된 플러그인에 해당하는 synced[0] 같은 태그의 행에 시작 시 이 메시지가 나타날 수 있었는데, 같은 기기의 다른 Claude Code 세션이 직전에 플러그인을 업데이트하며 파일을 옮겼을 때였습니다. 로드하려면 Claude Code를 재시작.)

마켓 루트의 --plugin-dir이 plugins/ 아래 플러그인을 로드하지 않음

claude --plugin-dir <path>로 시작했고 오류가 없는데 플러그인의 skill, agent, hook이 없습니다. --plugin-dir은 .claude-plugin/plugin.json과 skills/ 같은 구성요소 디렉터리가 있는 플러그인 루트 디렉터리를 받습니다. 마켓 루트를 주면 Claude Code는 marketplace.json을 읽지 않으므로 plugins/ 아래 플러그인은 로드되지 않고 오류도 없습니다. v2.1.281 이전에는 마켓 루트를 그 디렉터리 이름의 빈 플러그인 하나로 로드했습니다. 플러그인 디렉터리를 가리키세요.

claude --plugin-dir ./my-marketplace/plugins/my-plugin

이후 /plugin의 Installed를 열면 상세 pane이 구성요소를 나열합니다.

플러그인이 디렉터리 밖에서 참조하는 파일을 찾지 못함

--plugin-dir로는 동작하는데 설치 후 ../shared-utils 같은 경로 오류가 납니다. Claude Code는 설치된 플러그인을 캐시로 복사해 거기서 로드하므로 플러그인 자체 디렉터리 밖을 가리키는 경로는 캐시에서 아무것도 가리키지 않습니다. 공유 파일을 플러그인 디렉터리 안으로 옮기거나 그 안의 symlink로 참조하세요. 캐시 위치와 경로 해석은 Find plugins on disk.

Windows에서 ${CLAUDE_PLUGIN_ROOT}가 슬래시로 보임

Windows에서 플러그인 hook이 ${CLAUDE_PLUGIN_ROOT}를 C:\Users\you\...가 아닌 C:/Users/you/...로 받아 백슬래시를 기대한 스크립트가 깨집니다. Claude Code는 Windows에서 shell-form hook을 Git Bash로 실행하고 플러그인 루트를 의도적으로 슬래시 Win32 형태로 치환합니다. Bash 내장, MSYS 도구, 네이티브 Windows 바이너리가 모두 이 형태를 받습니다. 스크립트가 백슬래시가 필요하면 exec form과 shell form에 설명된 네이티브 경로를 유지하는 형태로 바꾸세요.

• args 배열로 프로세스를 직접 띄우는 exec-form hook
• "shell": "powershell"인 hook

플러그인은 로드되지만 skill이 없음

Installed에 오류 없이 나열되지만 /를 입력해도 skill이 나오지 않습니다. skill은 플러그인 루트의 skills/에서, command는 루트의 commands/에서 로드됩니다. .claude-plugin/ 안에는 plugin.json만 두며 .claude-plugin/ 안의 skills/ 디렉터리는 스캔되지 않습니다. 디렉터리를 플러그인 루트로 옮기고 /reload-plugins를 실행하세요. 이후 /plugin 상세 pane이 skill을 나열하고 / 입력이 제안합니다. 각 skill은 SKILL.md를 담은 디렉터리입니다. 매니페스트의 skills 항목이 디렉터리가 아닌 SKILL.md 파일을 가리키면 path is a file; skills entries must be directories containing SKILL.md로 보고됩니다.

skill은 로드되지만 Claude가 호출하지 않음

플러그인 skill은 /<plugin>:<skill> 명령을 입력하면 실행되지만 일반 요청에는 Claude가 호출하지 않습니다. 순서대로 확인:

• skill이 disable-model-invocation: true를 설정: Create your first plugin의 템플릿 skill이 설정합니다. Claude가 스스로 호출하길 원하는 skill에서는 그 줄을 제거. 필드는 Control who invokes a skill
• description이 사람들이 묻는 방식과 맞지 않음: Skill not triggering의 점검을 따름
• description이 잘림: 설치된 skill이 많으면 Claude Code가 목록의 글자 예산에 맞게 description을 줄여 Claude가 요청에 맞추는 데 필요한 키워드가 빠질 수 있음. Skill descriptions are cut short

현실적인 프롬프트 전반에서 skill이 얼마나 자주 발동하는지 하나씩 확인하는 대신 측정하려면 tool_used: Skill grader가 있는 eval 케이스를 쓰고 description을 바꿀 때마다 claude plugin eval을 실행하세요.

claude plugin eval init의 <directory> is not a plugin or skill folder

home 디렉터리나 플러그인을 하위 디렉터리에 두는 저장소 루트처럼 플러그인 루트가 아닌 디렉터리에서 claude plugin eval init을 실행했습니다. init은 작업 디렉터리 아래 suite를 쓰므로 플러그인이 보지 못할 evals/ 디렉터리를 만드는 대신 멈춥니다. .claude-plugin/plugin.json 또는 skill의 SKILL.md가 있는 플러그인 루트로 이동해 다시 실행하세요. 의도적으로 다른 곳에 suite를 만들려면 --eval-dir. Test plugins with evals.

userConfig 대화상자가 나타나지 않음

플러그인이 userConfig 옵션을 선언했는데 설치 시 구성 대화상자가 나타나지 않습니다. 설치가 값을 묻는지는 실행 위치에 달려 있습니다.

• 세션의 /plugin install 또는 /plugin의 Discover 탭: 대화상자가 이 대화형 설치의 일부
• VS Code 확장의 Manage plugins 대화상자: 설치 후 설정되지 않은 옵션을 폼으로 요청. v2.1.285 이전에는 거기서 설치하면 옵션 폼이 없어 터미널 세션에서 /plugin configure <plugin>@<marketplace>로 값을 설정해야 했음
• 셸의 claude plugin install: userConfig 값을 묻지 않음. 준 --config KEY=VALUE 값을 저장하고 옵션이 남으면 N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.를 출력. 설정되지 않은 옵션 중 필수가 있으면 not yet set 뒤에 (M required)가 붙음

셸에서 설치했다면 --config로 옵션마다 플래그 하나씩 값을 주세요.

claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

모든 옵션이 설정되면 설치 출력에 not yet set 줄이 없습니다. 나중에 대화상자를 열려면 세션에서 /plugin configure my-plugin@my-marketplace. 셸에서는 claude plugin configure가 아직 설정되지 않은 옵션을 보여주고 stdin으로 넘긴 값을 저장합니다 (Claude Code v2.1.285 이상). 매니페스트가 선언하지 않은 --config 키를 주면 플러그인은 설치되지만 ⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.와 플러그인이 선언한 키가 출력됩니다. 자체 user_config를 선언한 MCPB 번들 파일을 싣는 플러그인은 메시지가 isn't declared in this plugin's userConfig or by its bundled MCP servers.이고 알려진 키에 그 서버의 키가 <server>.<key>로 포함됩니다. 매니페스트가 URL로 참조하는 번들은 설치 시 읽지 않으므로 그 키는 나열되지 않습니다.

claude plugin validate가 오류를 보고

claude plugin validate <path> 또는 세션의 /plugin validate <path>가 Found N errors와 Validation failed를 출력하고 exit code 1로 끝났습니다. 검증기는 준 경로의 매니페스트를 읽습니다: 플러그인 디렉터리는 .claude-plugin/plugin.json, 마켓 디렉터리는 .claude-plugin/marketplace.json, 둘 다 있는 디렉터리는 둘 다. 마켓은 항목 자체 매니페스트의 문제에 항목 인덱스를 접두해 plugins[1] plugin.json → json: ...로 표시합니다. v2.1.289 이전에는 둘 다 있는 디렉터리를 마켓으로만 검증했습니다. 표는 검증을 멈추는 메시지와 --strict를 줄 때만 멈추는 두 경고(No frontmatter block found, Unknown field '<key>')를 다룹니다. 누락된 description 같은 다른 경고는 나열하지 않았습니다.

메시지	원인	해결
File not found: <path>	경로에 매니페스트가 없거나 경로가 없음	.claude-plugin/을 담은 플러그인/마켓 루트 디렉터리에 명령 실행
No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json	디렉터리에 .claude-plugin/ 매니페스트가 없음	매니페스트를 만들거나 올바른 디렉터리를 지목
Invalid JSON syntax: <parse error>	매니페스트나 hooks/hooks.json이 유효한 JSON이 아님	JSON을 고침. hooks/hooks.json을 고치기 전까지 세션은 그 파일의 hook 없이 플러그인을 로드
Path not found: <path>. The runtime loader will report this as a load failure.	매니페스트의 구성요소 경로가 없음	경로를 고치거나 디렉터리를 만듦
Path contains ".." which could be a path traversal attempt: <path>	구성요소 경로가 플러그인 디렉터리를 벗어남	플러그인 루트 안의 경로 사용
Path is a file; skills entries must be directories containing SKILL.md	skills 항목이 디렉터리 대신 SKILL.md를 가리킴	상위 디렉터리를 가리키거나 루트의 SKILL.md는 .
No frontmatter block found 또는 YAML frontmatter failed to parse: <error>	skill/agent/command 파일의 YAML frontmatter가 없거나 잘못됨	--- 구분자 사이에 frontmatter 추가·수정. 플러그인 디렉터리 검증 시 보고
Plugin name "<name>" is reserved: it passes as one of Anthropic's own	플러그인 name이 예약 이름 중 하나	하는 일에 맞게 이름 변경
Unknown field '<key>'	매니페스트에 스키마가 정의하지 않은 필드	제거하거나 메시지가 제안하는 이름 사용. Claude Code는 로드 시 알 수 없는 필드를 무시. privacyPolicyUrl 등 plugin.json의 디렉터리 등록 필드는 Directory listing fields

수정할 때마다 오류가 없을 때까지 다시 실행하세요. plugin.json 필드는 manifest reference, 마켓 수준 메시지는 마켓 검증 오류.

Plugin <name> has conflicting manifests

플러그인이 Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.로 로드에 실패합니다. 플러그인에 자체 plugin.json이 있고 마켓 항목이 strict: false이면서 commands, agents, skills, hooks, outputStyles, themes 중 하나를 선언합니다. 항목에서 그 필드를 제거하거나 항목에 strict: true를 설정해 Claude Code가 plugin.json에 덧붙이게 하세요. Strict mode.

Warning: No commands found in plugin <name> custom directory

플러그인이 로드될 때 ~/.claude/debug/<session-id>.txt의 claude --debug 로그에 Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories.가 기록됩니다. 세션이나 Errors 탭에는 아무것도 나타나지 않습니다. 매니페스트의 commands 경로는 있지만 .md 파일도 하위 디렉터리의 SKILL.md도 없습니다. command 파일을 추가하거나 매니페스트에서 경로를 제거하세요.

마켓 호스팅

마켓을 게시하는데 사용자가 오류를 보고하거나 자체 검증이 실패하는 마켓 소유자용 항목입니다.

URL 기반 마켓에서 상대 경로 플러그인이 실패

사용자가 https://example.com/marketplace.json URL로 마켓을 추가했습니다. source가 ./plugins/my-plugin 같은 상대 경로인 플러그인의 설치가 its marketplace entry path does not stay inside the marketplace directory로, 이미 설치된 플러그인의 로드가 Plugin source path refused로 실패합니다. 두 메시지 모두 error reference 항목이 있습니다. URL 기반 마켓을 추가할 때 Claude Code는 marketplace.json 파일 자체만 내려받고 그 서버에서 상대 경로로 플러그인 파일을 가져오지 않으므로 항목의 상대 경로는 가져온 적 없는 디렉터리를 가리킵니다. 각 항목에 Claude Code가 스스로 가져올 수 있는 소스(예: GitHub 저장소)를 주세요.

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

또는 마켓을 git 저장소에 호스팅하고 사용자에게 저장소 URL로 추가하게 하세요. git 소스는 Claude Code가 저장소 전체를 clone하므로 상대 경로가 해석됩니다. 소스 타입은 marketplace reference.

마켓 검증 오류

마켓 디렉터리에서 claude plugin validate .를 실행해 마켓 파일 자체에 대한 오류나 경고가 나왔습니다. claude plugin validate는 source가 로컬 경로인 각 항목도 검증하고 항목의 version이 플러그인 자체 매니페스트와 다르면 경고합니다. 항목 수준 메시지는 claude plugin validate가 오류를 보고의 플러그인 메시지에 plugins[N] plugin.json → 접두가 붙은 것입니다.

메시지	종류	해결
Duplicate plugin name "<name>" found in marketplace	오류	각 플러그인에 고유한 name
plugins[N].source 아래 Path contains "..": <path>	오류	.. 세그먼트 없이 마켓 루트 기준 상대 경로 사용
Marketplace name cannot contain control or bidirectional-formatting characters	오류	이름에서 escape나 개행 같은 문자를 제거
Plugin name cannot contain control or bidirectional-formatting characters	오류	플러그인 name에서 그 문자를 제거
Claude Code cannot install plugins from marketplace "<name>". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".	오류	메시지가 말하는 규칙에 맞게 마켓 이름 변경
Claude Code cannot install plugin "<name>". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".	오류	규칙에 맞게 항목 이름 변경
Marketplace has no plugins defined	경고	plugins에 항목을 하나 이상 추가
No marketplace description provided	경고	최상위 description 추가
plugins[N] plugin.json → name 아래 Plugin name "<name>" is not kebab-case	경고	소문자, 숫자, 하이픈으로 변경. claude.ai 마켓 sync가 그 형태를 요구
Entry declares version "<a>" but <path>/plugin.json says "<b>"	경고	항목을 plugin.json과 맞춤 (설치 시 plugin.json이 기준)
Marketplace name "<name>" is reserved in Claude Desktop	경고	마켓 이름 변경. Claude Desktop의 관리 마켓 sync는 대소문자 무관 org, org-provisioned, unknown을 거부
Marketplace name "<name>" is not accepted by Claude Desktop 또는 Plugin name "<name>" is not accepted by Claude Desktop	경고	영문자·숫자로 시작하는 최대 128자의 영문자, 숫자, ., _, -로 변경

v2.1.247 이전에는 제어/양방향 서식 문자를 포함한 마켓 이름이 Marketplace name impersonates an official Anthropic/Claude marketplace로만 보고됐습니다.

조직 정책 차단

조직이 플러그인을 제한하는 managed settings를 배포했고 명령이 정책 메시지로 거부됐습니다. 각 거부 뒤의 설정을 알려 관리자에게 무엇을 요청할지 알 수 있습니다. 관리자 측은 Manage plugins for your organization.

Marketplace source '<source>' is blocked by enterprise policy

/plugin marketplace add, update, 설치에서 이 줄로 거부됐습니다. GitHub/git 소스는 소스 뒤 괄호에 호스트가 붙습니다 ('github:owner/repo' (github.com)). 관리자가 managed settings에 blockedMarketplaces 또는 strictKnownMarketplaces를 설정했고 이 소스는 허용되지 않습니다. 관리자에게 소스 허용을 요청하거나 메시지가 나열한 허용 소스 중 하나를 추가하세요. 메시지의 나머지로 정책 종류를 구분합니다.

• Allowed sources: <list>: blockedMarketplaces blocklist가 아니라 strictKnownMarketplaces allowlist에서 온 차단
• No external marketplaces are allowed.: strictKnownMarketplaces allowlist가 비어 있음
• 단축형이 github.com을 가정한다는 Tip:: allowlist가 호스트 이름으로 git 호스트를 허용하는데 준 owner/repo 단축형이 github.com을 가리킴. 저장소가 내부 호스트에 있으면 git@your-git-host.com:owner/repo.git 같은 전체 URL로 다시 추가

정책이 더 엄격해지기 전에 추가한 마켓도 정책이 매 새로고침마다 적용되므로 새로고침이 멈춥니다.

Marketplace "<name>" is not in the allowed marketplace list

이미 등록한 마켓에 대해 Errors 탭이 이 줄 또는 Marketplace "<name>" is blocked by enterprise policy를 보여줍니다. 마켓 소스를 막는 같은 managed settings가 로드 시에도 적용됩니다. strictKnownMarketplaces에 이 마켓이 없거나 blockedMarketplaces가 지목해 Claude Code가 마켓과 플러그인의 로드를 중단합니다. allowlist 변형은 안내 줄이 허용 소스를 보여주거나 Contact your administrator to configure allowed marketplace sources.

Plugin "<name>" is blocked by your organization's policy and cannot be installed

설치가 이 줄로, 활성화가 cannot be enabled로 끝나는 같은 줄로, 설치/업데이트가 이유를 명시한 줄로 거부됐습니다: Plugin "<name>" is from marketplace "<marketplace>", which is blocked by your organization's policy 또는 Plugin "<name>" depends on "<dep>", which is blocked by your organization's policy. managed settings가 이 플러그인, 그 마켓, 또는 필요한 의존성을 차단합니다. 관리자에게 어느 항목이 적용되는지 문의하세요. 의존성이 차단되면 의존성의 마켓이 허용될 때까지 설치할 수 없습니다.

--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)

claude를 --plugin-dir, --plugin-url, --agents, --mcp-config로 시작했고 Claude Code가 이 메시지와 Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved.로 종료했습니다. 관리자가 임의 경로에서 플러그인·agent·서버를 로드하는 플래그를 끄는 disableSideloadFlags를 managed settings에 설정했습니다. 승인된 마켓에서 플러그인을 로드하거나 관리자에게 설정 제거를 요청하세요. 관련 Errors 탭 메시지는 --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings: managed settings가 그 플러그인을 이름으로 활성/비활성하며 플래그가 정책을 덮어쓰지 못하도록 --plugin-dir 사본을 무시합니다.

Plugins from ~/.claude/skills/ are blocked by your organization's managed settings

claude plugin init 또는 claude plugin enable이 이 줄로 멈췄습니다. 메시지가 strictKnownMarketplaces or blockedMarketplaces를 명시하며 관리자에게 strictKnownMarketplaces에 {"source":"skills-dir"}를 추가하거나 blockedMarketplaces에서 제거하라고 합니다. skills-dir 소스는 ~/.claude/skills/에서 로드하는 플러그인을 뜻합니다. 메시지가 명시한 변경을 관리자에게 요청하세요.

Command-sourced plugins are disabled by your organization's managed settings

command 소스 플러그인을 설치/업데이트했는데 이 줄과 The plugin was not installed or updated and its command was not run.로 멈췄습니다. 관리자가 disableCommandPluginSources를 설정해 Claude Code가 플러그인을 만드는 마켓 선언 명령의 실행을 거부합니다. disableCommandPluginSources가 미설정이면 allowManagedHooksOnly만 설정해도 같은 효과입니다. 정책이 허용하는 소스 타입으로 게시할 수 있는지 관리자에게 문의하세요.

Marketplace '<name>' is seed-managed

claude plugin marketplace update <name>이 Marketplace '<name>' is seed-managed (<dir>)와 관리자에게 문의하라는 힌트로 실패했습니다. 운영자가 CLAUDE_CODE_PLUGIN_SEED_DIR로 이 마켓을 미리 채웠고 Claude Code는 seed 관리 마켓을 읽기 전용으로 취급합니다. 일괄 marketplace update는 건너뛰고 나머지를 업데이트합니다. 마켓 내용을 바꾸려면 seed 이미지를 유지하는 사람에게 업데이트를 요청하세요. 절차는 Seed containers and CI.

체크리스트

• 받은 메시지를 이 페이지에서 정확히 검색 (단계별로 정리됨)
• 세션 안 /plugin 패널의 Errors 탭과 셸 claude plugin list / claude plugin list --json 확인
• 설치 후 이 세션에서 보이지 않으면 /reload-plugins
• 마켓 문제는 /plugin marketplace list, claude plugin marketplace update <name>
• 개발 중이면 claude plugin validate <dir>
• 정책 차단이면 메시지가 지목한 설정을 관리자에게 전달

함께 보기

• Plugin loading reference: 스코프, 캐시, 우선순위가 그렇게 동작하는 이유
• Plugin commands reference: claude plugin 명령의 플래그, 기본값, 출력, 종료 코드
• Install and manage plugins: 설치 단계 처음부터
• Manage plugins for your organization: 관리자용 정책 문제 해결

기준일

• 문서 작성·동기화 기준일: 2026-10-23 (v2.1.309 반영)
• 원문: https://code.claude.com/docs/en/plugins/troubleshooting