플러그인 문제 해결 - Claude Code Docs

이 페이지는 Claude Code 플러그인 및 마켓플레이스(Claude Code가 플러그인을 설치하는 카탈로그)의 오류 메시지 및 증상을 나열합니다. 각 항목은 원인, 한 가지 해결 방법, 그리고 해결 방법이 작동한 후 표시되는 내용을 제공합니다. 메시지가 플러그인 또는 마켓플레이스의 이름을 지정하는 경우, 항목은 <name> 같은 자리 표시자를 표시합니다. 플러그인을 설치하거나, 빌드하거나, 마켓플레이스를 호스팅하거나, 조직의 플러그인을 관리하는지 여부에 관계없이 이 페이지를 사용합니다.

이러한 경우는 다른 페이지에서 다룹니다:

범위, 캐시 및 우선순위가 작동하는 방식: 플러그인 로딩 참조를 읽습니다.
플래그, 필드 또는 명령 조회: 플러그인 명령 참조, 매니페스트 참조 또는 마켓플레이스 참조를 사용합니다.
hooks module not loaded 또는 hooks module did not load 메시지: 해당 플러그인은 mod이므로 mod가 로드되지 않음을 읽습니다.

본 페이지에서 본 정확한 메시지를 검색합니다. 각 메시지는 이를 생성하는 단계 아래에 나열되며, 이는 항상 실행한 명령이 아닙니다. 예를 들어, 마켓플레이스가 누락되어 설치가 실패할 수 있으므로 해당 메시지는 마켓플레이스 추가 아래에 있습니다.

`/plugin`이 실행되는 위치 찾기

/plugin은 실행 중인 Claude Code 터미널 세션 내에서 입력하는 명령이며, 대화형 패널을 엽니다. 이 섹션의 항목은 입력할 수 있지만 실행할 수 없는 위치와 존재하지 않는 명령 철자를 다룹니다.

`/plugin isn't available in this environment`

Claude Code 터미널 세션이 아닌 다른 곳에서 /plugin을 입력했고, Claude가 아무것도 열지 않고 이 줄로 응답했습니다. /plugin 패널을 그릴 터미널이 없는 세션에서 이 응답을 받습니다: claude -p를 사용한 비대화형 모드, Agent SDK, Claude 데스크톱 앱의 Code 탭, VS Code 확장 패널, 그리고 claude.ai/code의 브라우저. VS Code 확장 패널에서는 /plugin install <plugin>@<marketplace>와 같이 그 뒤에 무언가가 있는 /plugin 줄만 이 응답을 받습니다. 혼자 입력한 /plugin 또는 /plugins는 플러그인 관리 대화상자를 엽니다. 대신 사용 중인 표면에서 플러그인을 설치합니다:

Claude 데스크톱 앱, 로컬 또는 SSH 세션: 플러그인 설치 아래의 데스크톱 앱 탭을 사용합니다.
VS Code 확장: 플러그인 설치 아래의 VS Code 탭을 사용합니다.
웹의 Claude Code 또는 데스크톱 클라우드 세션: 클라우드 세션에는 플러그인 브라우저가 없습니다. 클라우드 세션이 로드하는 내용은 플러그인 설치의 클라우드 세션 탭을 참조합니다.
액세스 권한이 있는 터미널: 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 ...을 입력했고, 셸이 /plugin이라는 파일이 없다고 보고했습니다. Bash는 bash: /plugin: No such file or directory를 보고합니다. /plugin은 셸 프롬프트가 아닌 Claude Code 세션 내에서 입력하는 명령입니다. 세션을 시작하고 거기서 동일한 명령을 입력합니다:

claude

그런 다음 Claude Code 프롬프트에서:

/plugin install <plugin>@<marketplace>

성공적인 설치는 ✓ Installed <plugin>.로 시작하는 요약을 인쇄합니다. 설치 자체가 실패하면 해당 메시지는 마켓플레이스 추가 또는 플러그인 설치 아래에 있습니다. 세션을 시작하지 않고 셸에서 설치하려면 대신 claude plugin install <plugin>@<marketplace>를 실행합니다.

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

PowerShell 프롬프트에서 /plugin ...을 입력했고, /plugin은 프로그램이 아닌 Claude Code 명령입니다. Bash와 Zsh는 자신의 형태의 이 오류를 보고합니다. 대신 다음 중 하나를 사용합니다:

claude를 실행한 다음 Claude Code 프롬프트에서 /plugin을 입력합니다.
세션을 시작하지 않고 PowerShell에서 claude plugin install <plugin>@<marketplace>를 실행합니다.

`claude: command not found` after `claude plugin ...`

셸에서 claude plugin install ...을 실행했고, 셸이 claude를 전혀 찾을 수 없습니다. Windows에서 메시지는 'claude' is not recognized as the name of a cmdlet 또는 'claude' is not recognized as an internal or external command입니다. 원인은 플러그인 명령이 아닙니다. PATH 확인을 따른 다음 플러그인 명령을 재시도합니다.

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

어딘가에서 본 플러그인 명령을 입력했고 세션에서 Unknown command: /<name>을 받았거나, 셸의 claude 바이너리에서 error: unknown command '<name>' 또는 error: unknown option '<flag>'를 받았습니다. Claude Code가 없는 여러 명령 철자가 사용 중입니다. 아래 표는 각각을 실제 명령에 매핑합니다. 플러그인 명령 참조는 하위 명령과 해당 플래그를 나열합니다.

입력한 내용	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 또는 로컬 경로에서 Claude Code에 추가하는 카탈로그입니다. 이러한 항목은 추가 실패 또는 나중에 새로고침 실패 시 받는 메시지를 다룹니다.

`Marketplace "claude-plugins-official" not found`

세션에서 /plugin install <plugin>@claude-plugins-official을 실행했고, Claude Code가 해당 이름의 마켓플레이스가 없다고 보고했습니다. 공식 마켓플레이스가 이 머신에 아직 등록되지 않았습니다. Claude Code는 일반적으로 대화형 터미널 세션을 처음 시작할 때 자동으로 등록합니다. VS Code 확장을 통해서만 Claude Code를 사용했거나 해당 단계를 건너뛰거나 연기한 경우 아직 실행되지 않았습니다:

정책이 소스를 차단할 때
CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL이 설정되어 있을 때
재시도를 기다리는 실패한 시도 후

claude plugin 셸 명령은 절대 등록하지 않습니다. 추가한 다음 설치를 다시 시도합니다:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code는 Successfully added marketplace: claude-plugins-official을 인쇄하고, /plugin marketplace list는 소스와 함께 마켓플레이스를 표시합니다. 이 메시지의 다른 마켓플레이스 이름의 경우 Marketplace "<name>" not found를 참조합니다. 동일한 문자열은 /plugin Errors 탭, 로드 실패 목록인 패널에도 나타나며, 설정에 나열된 플러그인이 추가하지 않은 마켓플레이스의 이름을 지정할 때입니다.

`Marketplace "<name>" not found`

세션에서 /plugin install을 실행했고 Claude Code가 해당 이름의 마켓플레이스가 없다고 보고했습니다. 이 메시지에 도달하는 명령의 두 가지 형식이 있습니다:

/plugin install <plugin>@<name>: 설치 줄, 종종 누군가가 보낸 줄에서 추가하지 않은 마켓플레이스의 이름을 지정합니다. 이 항목의 나머지 부분은 찾기 및 추가를 다룹니다.
/plugin install <source> (경로, URL 또는 owner/repo 포함): 이 형식은 이미 추가한 소스에 대해서도 설치하는 대신 메시지를 보고합니다. 한 명령에서 소스에서 설치하려면 마켓플레이스 추가 및 한 명령에서 설치를 참조합니다.

이름이 claudeai-로 시작하면 마켓플레이스가 claude.ai에서 호스팅되며, 셸에서 claude plugin marketplace add --claudeai <name>으로 이름으로 추가합니다. claude.ai에서 마켓플레이스 추가를 참조합니다. 다른 이름의 경우, 설치 줄은 마켓플레이스의 이름을 지정하지만 마켓플레이스가 호스팅되는 위치를 말하지 않으며, Claude Code는 마켓플레이스 이름을 조회할 인덱스가 없습니다. 줄을 보낸 사람에게 마켓플레이스의 소스(GitHub owner/repo, git URL 또는 경로)를 요청합니다. 그런 다음 마켓플레이스를 추가하고 설치 줄을 다시 실행합니다. 누군가가 보낸 마켓플레이스는 타사이므로 설치하기 전에 플러그인을 검토합니다. 이미 마켓플레이스를 추가한 경우 /plugin marketplace list에 대해 철자를 확인합니다.

`Invalid marketplace source format`

/plugin marketplace add <source>, claude plugin marketplace add <source> 또는 claude plugin install <plugin> --marketplace <source>를 실행했고, Claude Code가 Invalid marketplace source format. Try: owner/repo, https://..., or ./path로 응답했습니다. Claude Code는 다음 형식 중 하나의 소스를 허용합니다:

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

claude-plugins-official과 같은 단순 이름은 이 중 어느 것도 일치하지 않습니다. marketplace.anthropic.com과 같은 단순 호스트명도 마찬가지입니다. 소스를 허용된 형식 중 하나로 다시 입력합니다:

/plugin marketplace add anthropics/claude-plugins-official

추가가 작동하면 Claude Code는 Successfully added marketplace: <name>을 인쇄합니다.

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

github.com/owner/repo 또는 gitlab.example.com/group/project 경로와 같이 owner/repo가 아닌 슬래시가 있는 소스를 전달했습니다. Claude Code는 이 메시지와 허용된 형식 목록으로 거부했습니다. owner/repo 단축형은 GitHub 전용이며 GitHub의 명명 규칙을 따라야 하므로 호스트명 또는 추가 경로 세그먼트가 실패합니다. 마켓플레이스가 호스팅되는 위치와 일치하는 형식으로 소스를 전달합니다:

모든 호스트의 저장소: 전체 클론 URL
호스팅된 marketplace.json: 해당 https:// URL
로컬 체크아웃: ./path 또는 절대 경로

예를 들어, 공식 마켓플레이스를 클론 URL로 추가하려면 세션에서:

/plugin marketplace add https://github.com/anthropics/claude-plugins-official.git

성공적인 추가는 Successfully added marketplace: <name>을 인쇄합니다.

`Invalid git URL`

마켓플레이스를 추가하거나, 플러그인을 설치하거나, git 주소에서 업데이트를 실행했고, 명령이 메시지에 Invalid git URL로 실패했습니다. Claude Code는 git을 실행하기 전에 모든 git 주소를 확인합니다. 지원하지 않는 프로토콜이 있는 주소를 거부합니다. 또한 git이 주소가 표시하는 것과 다른 서버 또는 폴더의 이름을 지정하는 것으로 읽을 수 있는 주소를 거부합니다. 주소 뒤의 텍스트는 변경할 내용의 이름을 지정합니다. 메시지가 말하는 대로 주소를 다시 작성하고 명령을 다시 실행합니다. 대신 is blocked by enterprise policy라고 말하는 거부는 조직의 설정에서 나옵니다. 마켓플레이스 소스가 엔터프라이즈 정책에 의해 차단됨을 참조합니다.

`Path does not exist: <path>`

marketplace add에 로컬 경로를 전달했고 해당 경로에 아무것도 없습니다. 상대 경로는 현재 디렉토리에 대해 확인됩니다. 메시지에서 확인된 경로를 확인합니다. 그런 다음 상대 경로가 시작되는 디렉토리에서 명령을 실행하거나 마켓플레이스 디렉토리에 절대 경로를 전달합니다. 성공적인 추가는 Successfully added marketplace: <name>을 인쇄합니다. 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`

Claude Code가 마켓플레이스를 클론하거나 다운로드했지만 내부의 예상 경로에서 marketplace.json을 찾지 못했습니다. 추가 명령은 Failed to add marketplace: Marketplace file not found at ...로 보고합니다. 기본 위치는 저장소 루트의 .claude-plugin/marketplace.json이며, 마켓플레이스 참조는 허용된 위치를 나열합니다. 수정은 소유자와 다른 모든 사람에게 다릅니다:

마켓플레이스를 소유한 경우: 파일을 해당 위치에 놓고 마켓플레이스를 다시 추가합니다.
다른 사람이 호스팅하는 경우: 정확한 소스를 게시하는 소유자에게 요청합니다.

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

마켓플레이스를 추가했는데, 해당 marketplace.json의 name이 my-plugin@my-marketplace와 같은 플러그인 id에서 @ 뒤에 오는 부분으로 유효하지 않습니다. Claude Code는 추가를 거부하고 아무것도 등록하지 않습니다. 메시지의 나머지 부분은 이름에 대한 규칙을 설명합니다. 이 예에서 _internal은 _로 시작하므로 규칙을 위반합니다:

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.

해당 규칙에 맞는 이름을 마켓플레이스에 지정한 다음 다시 추가합니다:

마켓플레이스를 소유한 경우: marketplace.json의 name을 예를 들어 internal-tools로 변경합니다.
다른 사람이 호스팅하는 경우: 소유자에게 이름 변경을 요청합니다.

v2.1.295 이전에는 Claude Code가 이 예의 추가를 성공한 것으로 보고했습니다.

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

마켓플레이스를 추가했는데, 해당 marketplace.json의 name이 constructor, toString, valueOf와 같이 모든 JavaScript 객체가 가진 멤버 이름 중 하나입니다. Claude Code는 이러한 이름을 예약해 두므로 추가를 거부하고 아무것도 등록하지 않습니다. 예약된 이름에 해당 이름이 나열되어 있습니다. 이 예에서 마켓플레이스의 이름은 constructor입니다:

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.

설정 파일이 extraKnownMarketplaces 아래에 마켓플레이스를 선언한 경우, Claude Code가 시작 시 실행하는 추가도 동일한 방식으로 실패하며 /plugin의 Errors 탭에 해당 메시지가 표시됩니다. 마켓플레이스에 다른 이름을 지정한 다음 다시 추가합니다:

마켓플레이스를 소유한 경우: marketplace.json의 name을 변경합니다.
다른 사람이 호스팅하는 경우: 소유자에게 이름 변경을 요청합니다.

v2.1.296 이전에는 이러한 마켓플레이스를 추가하면 이 메시지 대신 내부 오류로 실패했습니다.

`SSH authentication failed` 또는 `HTTPS authentication failed`

git 저장소에서 마켓플레이스를 추가하거나 업데이트했고, 클론이 Failed to clone marketplace repository:로 실패했으며 다음 줄 중 하나가 뒤따릅니다. 먼저 저장소 자체를 확인합니다: 철자가 잘못된 owner/repo, 존재하지 않는 저장소 또는 볼 수 없는 비공개 저장소도 이 메시지로 끝납니다. 브라우저에서 저장소 URL을 열거나 터미널에서 git ls-remote <url>을 실행하여 존재하고 액세스 권한이 있는지 확인합니다. 저장소가 맞으면 원인은 자격 증명입니다. Claude Code는 GIT_ASKPASS에 설정된 것을 포함하여 git의 프롬프트와 askpass 프로그램을 끄고, SSH를 배치 모드로 실행합니다. git이 프롬프트를 표시해야 하는 경우 클론 오류에 fatal: Cannot prompt because user interactivity has been disabled, terminal prompts disabled 또는 fatal: unable to get password from user가 포함됩니다. git이 프롬프트나 askpass 프로그램 없이 얻을 수 있는 자격 증명만 성공합니다:

SSH: ssh -T git@<host>는 암호 프롬프트 없이 성공해야 하며, 호스트는 이미 known_hosts에 있어야 합니다.
HTTPS: 자격 증명 도우미가 호스트에 대한 토큰을 보유해야 합니다. GitHub의 경우 gh auth login 및 gh auth setup-git을 실행합니다. 다른 호스트의 경우 git 자격 증명 도우미에 개인 액세스 토큰을 저장합니다. 테스트하려면 터미널에서 GIT_ASKPASS를 설정 해제하고 git -c core.askPass= ls-remote <url>을 실행합니다.

사용하는 프로토콜에 대한 확인이 프롬프트 없이 성공하면 추가 또는 업데이트를 다시 실행합니다. 성공적인 추가는 Successfully added marketplace: <name>을 인쇄합니다. 성공적인 업데이트는 셸에서 Successfully updated marketplace: <name>을 인쇄하거나 세션에서 ✔ Updated 1 marketplace을 인쇄합니다. Claude Code가 GitHub owner/repo 소스에 대해 SSH를 건너뛰도록 하려면 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1을 설정합니다. 없으면 Claude Code는 github.com에 대한 SSH 키가 구성된 것처럼 보일 때 SSH를 통해 해당 소스를 클론하고 SSH 클론이 실패할 때 HTTPS로 폴백합니다. 백그라운드 자동 업데이트가 자격 증명으로 수행할 수 있는 작업과 수행할 수 없는 작업은 백그라운드 자동 업데이트가 자격 증명으로 수행하는 작업을 참조합니다.

`SSH host key is not in your known_hosts file`

이전에 연결하지 않은 호스트에서 SSH를 통해 마켓플레이스를 추가했고, 클론이 이 줄과 ssh -T git@<host> 힌트로 실패했습니다. 키가 변경된 호스트의 경우 메시지는 SSH host key has changed이며 대신 ssh-keygen -R <host> 힌트입니다. Claude Code는 StrictHostKeyChecking=yes로 클론하므로 키를 자동으로 수락하는 대신 아직 수락하지 않은 호스트를 거부합니다. 터미널에서 한 번 연결하여 지문을 수락한 다음 다시 시도합니다:

ssh -T git@github.com

공개 저장소의 경우 SSH를 완전히 피하기 위해 마켓플레이스를 https:// URL로 추가합니다.

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

Windows에서 마켓플레이스를 추가했고 Claude Code가 Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory)를 보고했습니다. Claude Code는 PATH에서 git을 찾고 현재 디렉토리에서만 찾은 것을 실행하기를 거부합니다. 수정하려면 Git을 설치하고 다시 시도합니다:

Windows용 Git 설치

Windows용 Git을 설치하여 git이 PATH에 있도록 합니다.

새 터미널 열기

업데이트된 PATH가 적용되도록 새 터미널을 엽니다.

git이 실행되는지 확인

git --version이 버전을 인쇄하는지 확인합니다.

추가 다시 시도

marketplace add 명령을 다시 실행합니다.

`Git clone timed out after 120s`

마켓플레이스를 추가하거나 업데이트했고 Git clone timed out after 120s로 실패했으며, CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS를 설정하는 힌트가 뒤따릅니다. 마켓플레이스 클론 및 업데이트를 위해 다시 클론하면 기본적으로 120초가 소요됩니다. 큰 저장소 또는 느린 연결의 경우 제한을 높입니다. 값은 밀리초 단위입니다:

Bash 또는 Zsh
PowerShell

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

그런 다음 동일한 셸에서 다시 시도합니다. 저장소가 모노레포인 경우 claude plugin marketplace add <source> --sparse <paths>로 이름을 지정하는 디렉토리로 체크아웃을 제한합니다. 저장소에 큰 git 서브모듈이 있는 경우 Claude Code를 업데이트합니다. v2.1.295 이상에서는 Claude Code가 플러그인 파일이 있는 서브모듈만 가져옵니다. 이전 버전은 모든 서브모듈을 가져오며, 이것만으로도 120초를 모두 소진할 수 있습니다.

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

마켓플레이스의 git 호스트에 도달할 수 없는 환경에서 작업하고 있으며, 모든 세션이 백그라운드에서 실패한 새로고침을 반복합니다. 마켓플레이스의 기존 체크아웃은 제자리에 남아 있고 시작이 지연되지 않습니다. 각 세션에서 자동 업데이트가 켜진 마켓플레이스의 경우 Claude Code는 백그라운드에서 마켓플레이스의 git 호스트에서 새 커밋을 확인합니다. 해당 확인이 호스트에 도달할 수 없으면 마켓플레이스를 다시 클론하려고 시도하고 오프라인에서 해당 클론도 실패합니다. 호스트에 도달할 수 없을 때 다시 클론 시도를 건너뛰고 기존 체크아웃을 계속 사용하려면 이 변수를 설정합니다:

Bash 또는 Zsh
PowerShell

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

$env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

변수가 설정되면 Claude Code는 이미 .claude-plugin/marketplace.json을 포함하는 체크아웃에 대해서만 다시 클론을 건너뜁니다. 클론되지 않았거나 클론이 중간에 중단된 마켓플레이스는 여전히 클론 시도를 받으므로 온라인 상태에서 한 번 추가합니다. 완전히 오프라인 배포의 경우 컨테이너 및 CI 시드를 따르는 CLAUDE_CODE_PLUGIN_SEED_DIR을 사용하여 이미지 빌드 시간에 플러그인 디렉토리를 미리 채웁니다.

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

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로 응답하면 먼저 마켓플레이스를 추가합니다.

새로고침 힌트가 있는 `not found in marketplace`

힌트는 Your local copy may be out of date — try claude plugin marketplace update <marketplace> 또는 The marketplace couldn't be refreshed (...)를 읽습니다. Claude Code가 조회 전에 마켓플레이스를 새로고침하지 않았습니다(예: 오프라인 상태일 때). 카탈로그 사본이 오래되었을 수 있습니다. 마켓플레이스 이름으로 새로고침한 다음 다시 설치합니다:

/plugin marketplace update <marketplace>

claude plugin marketplace update는 Successfully updated marketplace: <name>을 인쇄하고, /plugin marketplace update는 ✔ Updated 1 marketplace을 표시합니다. 재시도된 설치가 동일한 메시지를 인쇄하면 not found in marketplace (힌트 없음)에서 설명하는 대로 이름을 확인합니다. Claude Code가 설치 전에 마켓플레이스를 새로고침할 때는 새로고침이 실행되지 않는 다른 경우를 나열합니다.

힌트가 없는 `not found in marketplace`

이름이 가장 가능성 있는 문제입니다. /plugin을 열고 Discover로 이동한 다음 목록에서 이름을 복사합니다. v2.1.232 이전에는 Claude Code가 조회 후에만 명명된 마켓플레이스를 새로고침했으며 자동 업데이트가 켜져 있을 때만 그렇게 했습니다.

`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은 자동 업데이트가 켜진 마켓플레이스만 새로고침합니다. 마켓플레이스의 이름을 지정하면 Claude Code가 조회 전에 새로고침합니다:

/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`

이미 사용자 범위 또는 관리형 설정으로 설치된 플러그인에 대해 /plugin install을 실행했고, Claude Code가 Use '/plugin' to manage existing plugins.로 거부했습니다. 플러그인 이름을 @<marketplace> 없이 입력한 경우 메시지는 globally를 생략합니다. 플러그인은 이미 모든 프로젝트에서 사용 가능하므로 추가할 것이 없습니다. 범위를 변경하거나 활성화 또는 비활성화하거나 구성하려면 /plugin을 열고 Installed로 이동합니다. 프로젝트 또는 로컬 범위에만 설치된 플러그인은 이 메시지를 트리거하지 않습니다. Claude Code를 사용하면 사용자 범위에서도 설치할 수 있으므로 다른 프로젝트에서 사용할 수 있습니다. 셸의 claude plugin install은 다른 메시지를 인쇄합니다. 대상 범위에 이미 설치된 플러그인의 경우 Plugin "<name>@<marketplace>" is already installed (scope: user)를 인쇄하고 종료 코드 0으로 종료합니다. 캐시 디렉토리가 누락된 경우 동일한 명령이 다시 다운로드합니다. claude plugin install, /plugin 또는 세션의 설치 제안을 통해 플러그인을 설치했고, Claude Code가 이 줄로 거부했거나 would share its saved data with로 거부했습니다. 거부된 플러그인의 id와 설치된 플러그인의 id는 디스크의 동일한 폴더에 매핑됩니다: .과 @이 -로 작성되면 동일합니다. macOS 및 Windows에서 대문자만 다른 id도 동일한 폴더에 매핑됩니다. 둘 다 설치하면 한 플러그인의 파일이 다른 플러그인의 폴더에 들어가므로 Claude Code는 거부하고 설치된 플러그인이 파일을 유지합니다. 메시지는 해결 방법을 지정합니다:

다른 플러그인이 설치됨: 메시지는 Only one of the two can be installed.라고 말하고 다른 플러그인을 제거하는 claude plugin uninstall 명령 또는 /plugin의 제거 단계를 지정합니다. 실행한 다음 다시 설치합니다. 제거가 제거하는 것에 대해서는 제거가 삭제하고 유지하는 것을 참조합니다.
두 id가 한 번의 설치에 도착함: 플러그인과 필요한 의존성 같은 경우: 설치 순서는 도움이 되지 않습니다. 두 플러그인을 나열하는 마켓플레이스의 유지 관리자만 이름을 바꿔서 수정할 수 있습니다. 두 플러그인이 다른 마켓플레이스에서 올 때 둘 중 하나의 유지 관리자가 수정할 수 있습니다.

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

마켓플레이스 항목이 이 버전의 Claude Code가 가져올 수 없는 소스 유형을 사용하는 플러그인을 설치했고, Claude Code가 이 메시지와 Update Claude Code and try again.으로 중단되었습니다. Claude Code를 업데이트한 다음 설치를 다시 시도합니다. 소스 유형은 마켓플레이스 참조에 있습니다.

`Plugin archive integrity check failed`

zip 아카이브로 배포되는 플러그인을 설치했고, Claude Code가 이 줄과 The archive was not installed.로 거부했습니다. 플러그인의 마켓플레이스 항목은 sha256 핀이 있는 archive 소스를 사용하고, 다운로드된 파일의 다이제스트가 핀과 일치하지 않습니다. 전체 메시지는 다음과 같습니다:

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이 제공하는 정확한 파일의 다이제스트를 다시 계산하고 마켓플레이스 항목의 sha256을 업데이트합니다. shasum -a 256 my-plugin.zip을 사용하거나 PowerShell에서 Get-FileHash -Algorithm SHA256 my-plugin.zip을 사용합니다.
플러그인을 설치하는 경우: 세션에서 /plugin marketplace update <name>을 실행하여 항목이 수정된 경우 카탈로그를 새로고침한 다음 설치를 다시 시도합니다. 새로고침 후에도 다이제스트가 계속 불일치하면 설치하기 전에 마켓플레이스 소유자에게 어떤 파일을 핀했는지 물어봅니다.

`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 플러그인 소스 참조가 허용하는 값으로 변경하거나, 항목을 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 이전에는 Claude Code가 마켓플레이스를 추가할 때만 이름을 확인했으므로 이름이 예약되기 전에 등록된 항목이 계속 로드되었습니다.

`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가 클론하거나 가져오기를 거부하는 URL입니다.
Its source doesn't match its extraKnownMarketplaces entry in user or managed settings: 항목이 같은 이름의 extraKnownMarketplaces 선언과 일치하지 않습니다.

이유 대신 (see the debug log)가 is added but ignored 뒤에 오면 Claude Code가 마켓플레이스의 이름을 거부한 것입니다(예: 예약된 이름의 다른 철자). 디버그 로그에 해당 항목이 표시됩니다. 수행할 작업:

메시지의 수정 방법을 따릅니다. 셸에서 claude plugin marketplace remove <name>을 실행한 다음, 지원되는 소스 또는 로컬 경로에서 마켓플레이스를 다시 추가하고 해당 플러그인을 다시 설치합니다. remove 명령은 이 플러그인들을 제거합니다. remove 명령은 무시된 항목에도 작동합니다.
네트워크 위치의 마켓플레이스를 유지하려면 사용자 또는 관리형 설정의 extraKnownMarketplaces 아래에 선언합니다. 저장소의 .claude/settings.json 또는 .claude/settings.local.json에 있는 선언은 인정되지 않습니다.
설정 선언과 다른 소스의 경우 선언된 소스에서 마켓플레이스를 다시 추가하거나 선언을 변경합니다. claude plugin marketplace add도 같은 불일치를 거부합니다. 해당 Cannot add marketplace 항목을 참조합니다.
거부된 이름의 경우 마켓플레이스를 제거합니다. 줄에 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)로 보고했습니다. 이유는 디버그 로그에만 나타났습니다. 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 Code가 플러그인을 가져왔다가 .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>":로 보고하고 종료 코드 1로 종료합니다. 플러그인 작성자가 파일을 수정해야 하며 그때까지 플러그인을 설치할 수 없습니다:

본인이 작성자인 경우: 셸에서 claude plugin validate <plugin-directory>를 실행하여 문제가 되는 경로와 함께 동일한 오류를 확인하고 파일을 수정합니다.
본인이 작성자가 아닌 경우: 메시지를 마켓플레이스 소유자에게 보고합니다.

`Plugin directory not found at path: <path>`

/plugin의 Errors 탭은 마켓플레이스가 ./plugins/my-plugin과 같은 상대 경로로 나열하는 활성화된 플러그인에 대해 이를 표시하며, 마켓플레이스 내부의 해당 경로에 디렉토리가 없습니다. 마켓플레이스를 유지 관리하는 경우 항목의 source 경로를 수정하거나 폴더를 복원합니다. 그렇지 않으면 메시지를 마켓플레이스 소유자에게 보고합니다. Marketplace directory not found at path: <path>는 마켓플레이스 자체의 디렉토리가 누락되었음을 의미합니다. 로컬 경로에서 추가한 마켓플레이스의 경우 해당 디렉토리가 이동되었거나 삭제되었습니다. 복원하거나 마켓플레이스를 제거하고 새 위치에서 다시 추가합니다.

`No plugins available` 또는 `No marketplaces configured`

/plugin을 열었고 Discover 탭이 비어 있거나 claude plugin marketplace list가 No marketplaces configured를 인쇄했습니다. 등록된 마켓플레이스가 없으므로 표시할 카탈로그가 없습니다. 세션에서 공식 마켓플레이스 anthropics/claude-plugins-official을 추가합니다:

/plugin marketplace add anthropics/claude-plugins-official

Claude Code는 Successfully added marketplace: claude-plugins-official을 인쇄하고 Discover는 해당 플러그인을 나열합니다. Anthropic 마켓플레이스 페이지는 추가할 수 있는 다른 마켓플레이스를 나열합니다.

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

세션 또는 셸에서 설치 명령의 --marketplace <source>로 새 마켓플레이스 소스를 지정했습니다. Claude Code가 해당 소스에서 가져온 카탈로그가 다른 소스에서 이미 추가한 마켓플레이스와 동일한 이름을 가지고 있습니다. 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에 대한 extraKnownMarketplaces 항목이 사용자 설정 또는 관리형 설정에 이미 있습니다. 지정한 소스가 해당 항목에 나열된 소스와 다르므로 Claude Code는 추가를 거부하고 아무것도 등록하지 않습니다. 두 소스는 유형이 같고 모든 필드의 값이 같을 때 일치합니다. 전달하지 않은 ref를 설정하는 항목은 다른 것으로 간주됩니다. github 항목은 저장소를 https://github.com/ URL로 지정한 경우에도 다른 것으로 간주됩니다. Claude Code가 해당 URL을 git 소스로 기록하기 때문입니다. 다음 중 하나를 수행합니다:

선언된 소스 사용: Claude Code는 설정에 선언된 마켓플레이스를 자동으로 등록하므로 먼저 세션에서 /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 항목을 편집하거나 제거한 다음 마켓플레이스를 다시 추가합니다. 관리형 설정이 선언하면 관리자에게 문의합니다.

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)

였습니다. /plugin 메뉴에서 설치할 플러그인을 선택했고, 아무것도 설치되지 않았으며, 메뉴가 실패한 내용의 요약으로 닫혔습니다. 실패한 클론 후 git의 출력과 같은 일부 이유는 첫 번째 줄만 표시합니다. 그러한 이유가 단축되면 요약은 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>`

플러그인을 설치할 때 Claude Code는 파일의 새 사본을 다운로드하고 플러그인 캐시의 해당 버전 폴더로 이동합니다. 이 메시지는 이동이 실패했음을 의미하며, 일반적으로 설치가 실행되는 동안 다른 프로그램이 폴더를 사용하고 있기 때문입니다. 파일 시스템 코드는 괄호에 나타납니다:

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 탭에 나타나며, Claude Code는 문제를 해결할 때까지 영향을 받는 플러그인을 비활성화된 상태로 유지합니다.

표는 각 메시지와 수정을 나열합니다. 작성자로서 의존성을 선언하려면 플러그인 의존성을 참조합니다.

메시지	의미	해결 방법
`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>`를 실행하여 마켓플레이스에서 의존성을 설치합니다. 그러면 claude.ai 사본 대신 마켓플레이스 사본이 로드됩니다.
`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 "<marketplace>", which is not in the allowlist`	의존성이 다른 마켓플레이스에 있고 교차 마켓플레이스 해결이 기본적으로 꺼져 있습니다.	동일한 범위에서 의존성을 직접 설치합니다. 셸에서 `claude plugin install <dep>@<marketplace>` 및 플러그인을 설치하는 `--scope`를 사용한 다음 다시 시도합니다.

이를 프로그래밍 방식으로 보려면 셸에서 claude plugin list --json을 실행합니다. 문제가 있는 플러그인은 메시지가 있는 errors 필드와 각각에 대한 type이 있는 errorDetails 필드를 전달합니다: 처음 세 행은 dependency-unsatisfied이고 네 번째는 dependency-version-unsatisfied입니다.

플러그인이 설치되었지만 작동하지 않음

설치가 성공했지만 플러그인의 스킬, 훅 또는 서버가 아무것도 하지 않습니다. 플러그인이 나타나지 않거나 스킬이 표시되지 않음으로 시작합니다. 이는 Claude Code가 로드한 내용을 보고하는 위치를 알려주고 메시지와 일치합니다.

플러그인이 나타나지 않거나 스킬이 표시되지 않음

플러그인을 설치했고 /를 입력하여 스킬을 기대했거나 Claude에게 사용하도록 요청했으며 아무것도 일어나지 않았습니다. 변경하기 전에 플러그인의 상태를 확인합니다:

플러그인이 설치되고 활성화되었는지 확인

/plugin을 실행하고 Installed를 엽니다. 플러그인이 나열되고 활성화되었는지 확인합니다. 셸의 claude plugin list는 각 플러그인의 버전, 범위 및 Status: ✔ enabled와 함께 동일한 목록을 인쇄합니다.

Errors 탭 읽기

동일한 패널에서 Errors 탭을 엽니다. 각 항목은 메시지를 지침 줄과 쌍으로 만듭니다. 이 섹션의 나머지 부분의 대부분의 메시지는 해당 탭에서 나옵니다.

이 세션 중에 설치한 경우 다시 로드

플러그인이 설치되고 오류가 없지만 이 세션 중에 설치한 경우 /reload-plugins를 실행합니다. 플러그인, 스킬, 에이전트, 훅 및 서버의 개수와 함께 Reloaded:를 인쇄합니다. 무언가가 실패하면 N errors during load. Run /plugin for details.를 추가합니다.

플러그인이 오류 없이 로드되지만 스킬이 여전히 나타나지 않으면 다음 단계는 자신의 플러그인과 다른 사람의 플러그인에 따라 다릅니다:

빌드 중인 플러그인: 플러그인이 로드되지만 스킬이 누락됨을 참조합니다.
다른 사람이 게시한 플러그인: /plugin에서 Installed를 열고 플러그인의 세부 정보 창을 열어 플러그인에 포함된 내용을 나열합니다. 거기에 스킬이 나열되지 않은 플러그인은 /를 입력할 때 제공할 스킬이 없습니다.

`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 이전에는 해당 요약의 스킬 개수가 플러그인의 commands/ 항목만 포함했으므로 다시 로드가 플러그인의 SKILL.md 스킬을 로드하고 여전히 0 skills를 보고할 수 있었습니다.

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

/plugin과 claude plugin list는 의존성 설치 후 node_modules 디렉토리가 남지 않은 플러그인에 이 메모 중 하나를 표시합니다. 플러그인은 로드되지만 누락된 패키지가 필요한 부분은 작동하지 않을 수 있습니다.

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 잠금 파일, 또는 이 컴퓨터에 해당 패키지 관리자가 설치되지 않은 잠금 파일과 같은 이유가 명시됩니다. 해당 이유가 해소되지 않는 한 플러그인을 업데이트해도 패키지가 설치되지 않습니다. 이유가 잠금 파일이라면 플러그인 작성자가 이를 교체해야 합니다. 패키지 관리자가 누락된 경우라면 이를 설치한 다음 플러그인을 업데이트합니다.

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

Errors 탭은 이 줄을 Run /plugin to refresh the plugin cache의 지침과 함께 표시합니다. Claude Code는 플러그인에 대한 설치 기록을 가지고 있지만 기록이 가리키는 디렉토리가 누락되었습니다(예: 캐시를 지운 후). 셸에서 플러그인을 다시 설치합니다. claude plugin install <name>@<marketplace>는 설치 디렉토리가 누락되었지만 기록이 존재하는 플러그인을 다시 다운로드합니다:

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(아마도 더 최신 버전)가 작성했을 것입니다. 기록이 있는 동안 이 버전은 파일을 다시 작성하지 않으므로 기록이 손실되지 않습니다. 메시지의 옵션을 순서대로 가져옵니다:

claude update로 Claude Code를 업데이트합니다.
업데이트할 수 없으면 기록을 작성한 Claude Code 버전으로 명명된 플러그인을 제거합니다.
둘 다 도움이 되지 않으면 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의 어떤 버전도 사용할 수 없습니다. 파일의 나머지는 정상적으로 로드됩니다. Claude Code는 사용할 수 없는 기록을 .set-aside 파일로 복사하고 목록에서 삭제합니다. Claude Code는 복사본을 다시 읽지 않으며 복사본은 cleanupPeriodDays 일정에 따라 만료됩니다.

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

명령은 작동했습니다. 경고에 명시된 설정 파일에 오류가 있으므로, 이를 수정할 때까지 Claude Code는 명령이 해당 파일에 기록한 내용을 포함하여 파일 전체를 무시합니다. 경고에 명시된 오류를 수정합니다. Claude Code가 허용하지 않는 값의 경우 손상된 설정 파일 수정에서 방법을 설명합니다. 그런 다음 명령의 변경 사항이 더 이상 파일에 없으면 명령을 다시 실행합니다. 이 경고는 셸에서 실행한 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가 허용하지 않는 값이 있습니다. 허용되는 값은 설정 참조에서 해당 설정을 찾아 확인합니다. 둘 이상의 값이 실패하면 텍스트는 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가 사용자 설정을 재정의하고 있습니다. 머신에서 프로젝트 활성화 플러그인을 거부하려면 id를 .claude/settings.local.json에서 false로 설정합니다. 이는 프로젝트 파일보다 우선순위가 높습니다. 메시지가 이름을 지정할 수 있는 다른 소스의 경우 사용자 설정에서 비활성화되었지만 여전히 로드됨을 참조합니다. claude plugin list가 대신 플러그인을 required by your org로 표시하면 설정 파일이 관련되지 않습니다: 조직이 claude.ai에서 동기화된 플러그인을 필수로 표시하고 이전에 비활성화했더라도 로드됩니다. claude.ai에서 동기화된 플러그인을 참조합니다.

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

Errors 탭은 프로젝트의 .claude/settings.json이 활성화하는 플러그인에 대해 이 줄을 Run claude plugin install <name>@<marketplace> --scope project to install it for this project의 지침과 함께 표시합니다. 저장소의 설정은 모든 사람이 플러그인을 활성화할 수 있지만 설치하지는 않습니다. 플러그인이 GitHub 저장소 또는 npm 패키지와 같은 외부 소스에서 나올 때 Claude Code는 직접 설치할 때까지 다운로드하지 않습니다. 지침 줄의 명령을 셸에서 실행한 다음 다시 로드합니다:

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

세션에서 /reload-plugins를 실행한 후 Errors 탭 항목이 사라지고 플러그인이 Installed 아래에 나열됩니다. 조직이 플러그인을 미리 설치하면 대신 관리 설정을 통해 그렇게 합니다. 플러그인 사전 설치 및 필수를 참조합니다.

Windows에서 `plugin uninstall` 후에도 플러그인이 설치된 상태로 남음

Windows에서 프로젝트 또는 로컬 범위로 claude plugin uninstall을 실행하면 성공했다고 보고되지만, claude plugin list 또는 /plugin에 여전히 플러그인이 나열됩니다. installed_plugins.json에 프로젝트 폴더에 대한 플러그인 설치 기록이 두 개 있었고, 각 기록은 폴더 경로를 서로 다르게 표기하며, 한 번의 제거로는 그중 하나만 삭제됩니다. 확인하려면 셸에서 claude plugin list --json을 실행합니다. 남아 있는 플러그인 행의 projectPath는 제거를 실행한 위치와 폴더를 다르게 표기합니다(예: C:\work\app에 대해 c:\work\app). 같은 폴더에서 같은 --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를 실행한 다음 제거를 다시 실행합니다.

git 저장소에서 설치한 플러그인의 버전이 `unknown`으로 표시됨

claude plugin list의 Version: unknown은 Claude Code가 git 소스 플러그인의 버전으로 사용하는 커밋을 읽지 못했음을 의미할 수 있습니다. 플러그인은 자체 저장소를 가지고 있거나 git으로 호스팅되는 마켓플레이스 내부에 있을 수 있습니다. 셸에서 다음 명령을 실행합니다. formatter@my-marketplace는 claude plugin list에 표시된 플러그인의 name@marketplace 줄로 바꿉니다:

Claude Code 업데이트

Claude Code를 업데이트하여 v2.1.302 이상으로 만듭니다. 이 버전은 커밋을 읽을 수 있는 형식으로 클론합니다:

claude update

마켓플레이스 업데이트

마켓플레이스 저장소 내부 플러그인의 커밋을 보관하는 Claude Code의 마켓플레이스 사본을 업데이트합니다:

claude plugin marketplace update my-marketplace

플러그인 업데이트

플러그인을 업데이트하여 기록된 버전을 다시 작성합니다:

claude plugin update formatter@my-marketplace

버전 확인

Version: 줄에 12자 커밋 ID와 같은 값이 있는지 확인합니다:

claude plugin list

claude plugin update는 실행할 때마다 한 범위의 블록을 변경합니다. 여전히 unknown이 표시되는 블록의 경우 해당 블록의 Scope: 값으로 다시 실행합니다:

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

다시 실행한 후에도 블록에 여전히 unknown이 표시되면 추가 도움 받기를 참조합니다.

`Failed to load hooks from <path>` 및 발화하지 않는 훅

플러그인의 훅이 실행되지 않거나 하나가 작업을 차단합니다. Errors 탭이 로드 실패를 표시하거나, 훅이 로드되고 트랜스크립트에서 <Event> hook error 공지를 보거나, 훅이 오류 없이 로드되고 절대 발화하지 않습니다.

훅이 로드되지 못함

Errors 탭은 다음 메시지 중 하나를 표시합니다:

Failed to load hooks from <path>: <reason>: hooks/hooks.json이 유효한 JSON이 아니거나 훅 스키마가 실패합니다. 이유는 구문 분석 또는 유효성 검사 오류의 이름을 지정합니다. 파일을 수정합니다. 플러그인을 게시하기 전에 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를 참조합니다.

트랜스크립트의 `hook error` 공지

... hook error: Failed with non-blocking status code: <stderr> 형식의 공지는 훅이 실행되고 명령이 실패했음을 의미합니다. 예를 들어 Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found는 Claude Code가 생성한 셸이 node를 찾을 수 없음을 의미합니다. 설치하거나 claude를 시작하는 터미널의 PATH에 있는지 확인합니다. stderr이 플러그인의 경로를 공백에서 자르면 훅의 셸 형식 명령이 ${CLAUDE_PLUGIN_ROOT}를 따옴표 외부에서 사용하고 설치 경로에 공백이 포함되어 있습니다. 변수를 큰따옴표로 감싸거나 exec 형식을 사용합니다. 따옴표 없는 변수를 찾으려면 플러그인 디렉토리에서 claude plugin validate를 실행하고 따옴표 경고를 찾습니다. 공지가 Failed to run: Plugin directory does not exist: <path>로 표시되면 Plugin directory does not exist를 참조합니다. 다른 오류의 경우 플러그인 디렉토리에서 훅의 명령을 직접 실행하여 전체 출력을 보거나 디버그 로깅으로 전체 stderr을 캡처합니다.

플러그인 훅이 도구 호출 또는 프롬프트를 차단

종료 코드 2로 종료하는 훅은 실행한 작업을 차단합니다. 플러그인의 훅이 이런 방식으로 차단하고 stderr이 차단 메시지일 때 오류는 This hook comes from the <plugin> plugin.으로 끝나므로 비활성화하거나 수정할 플러그인을 알 수 있습니다. v2.1.281 이전에는 오류가 플러그인의 이름을 지정하지 않았습니다. 해당 메시지가 플러그인의 경로를 공백에서 자르면 따옴표 없는 ${CLAUDE_PLUGIN_ROOT} 수정을 적용합니다.

훅이 로드되지만 절대 발화하지 않음

훅이 오류 없이 로드되지만 절대 발화하지 않으면 먼저 세션에서 /plugin을 실행하고 플러그인의 세부 정보를 엽니다. 그곳에 Its hooks.json hooks do not run으로 시작하는 메모가 있으면 같은 이름을 가진 다른 활성화된 플러그인이 대신 훅을 등록했다는 의미이며, 두 개의 활성화된 플러그인이 이름을 공유할 때의 훅에서 어느 사본인지와 전환 방법을 설명합니다. 그렇지 않으면 훅의 정의를 확인한 다음 실행되는 모습을 지켜봅니다:

이벤트 이름 확인

이벤트 이름은 대소문자를 구분하므로 정확히 일치하는지 확인합니다(예: PostToolUse).

매처 확인

훅의 matcher가 도구 이름과 일치하는지 확인합니다.

의도적으로 이벤트 트리거

PostToolUse 훅의 경우 Claude에게 파일을 편집하도록 요청합니다.

디버그 로그 읽기

디버그 로그를 열어 어떤 훅이 일치했는지 기록합니다. 실행된 훅은 종료 코드와 함께 거기에 나타납니다.

`Plugin directory does not exist: <path>`

메시지에 다시 설치하라고 나와 있더라도 먼저 Claude Code 프롬프트에서 /reload-plugins를 실행합니다. 세션이 플러그인의 훅을 로드한 디렉토리가 디스크에서 사라지면 플러그인의 훅이 Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)로 실패하고 훅이 실행되지 않습니다. Plugin directory not found at path: <path>는 마켓플레이스 항목에 관한 다른 메시지입니다. 다시 로드하면 플러그인의 현재 디렉토리에서 훅을 로드합니다. 실패는 각 훅 이벤트와 명령마다 세션당 한 번만 표시되므로, 훅이 더 이상 오류를 표시하지 않는다고 해서 문제가 해결되었음을 확인할 수는 없습니다. 대신 다시 로드의 출력을 읽습니다:

오류 줄이 없는 Reloaded:: 플러그인의 훅이 더 이상 누락된 디렉토리를 가리키지 않습니다.
N errors during load. Run /plugin for details.: /plugin에서 Errors 탭을 열고 표시된 메시지에 대한 이 페이지의 항목을 따릅니다.
Run /reload-plugins --force to apply.로 끝나는 줄: 아무것도 다시 로드되지 않았으며 훅이 계속 실패합니다. 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 경우는 플러그인 명령이 user_config를 참조 아래에 자체 항목이 있습니다.

`Bundled MCP server "<name>" was not started: it needs configuration`

플러그인은 서버를 MCPB 번들로 포함하고 user_config를 선언하며, 필수 설정에 저장된 값이 없거나 저장된 값이 번들 자체의 유효성 검사에 실패하므로 Claude Code는 서버 시작을 건너뜁니다. 플러그인의 나머지는 작동합니다. /plugin의 Installed 탭에서 플러그인을 선택하고 Configure를 선택하여 값을 제공합니다. 저장한 후 /plugin은 Configuration saved.를 표시하고 닫으며 Claude Code는 설치된 플러그인 관리 아래에 설명된 대로 플러그인을 다시 로드합니다. 해당 다시 로드가 적용되면 서버가 시작됩니다. v2.1.285 이전에는 Claude Code가 이 줄을 표시하지 않고 서버를 건너뛰었습니다.

서버가 구성되었지만 절대 연결되지 않음

/mcp를 실행하여 서버의 상태를 확인합니다. 서버가 정상이면 /mcp는 연결된 것으로 나열합니다. 서버가 시작되는 동안 인쇄한 오류를 읽으려면 claude --debug를 실행하고 ~/.claude/debug/<session-id>.txt에서 로그를 엽니다. --debug 플래그는 터미널에 인쇄하지 않습니다.

claude --debug를 실행하기 전 15분 이내에 플러그인의 stdio 서버 연결이 실패한 경우 Claude Code는 서버를 시작하지 않습니다. 새 세션에서 /mcp의 서버 메뉴에서 Reconnect를 선택하여 서버를 시작한 다음 로그를 엽니다.

.mcp.json의 서버 항목이 스키마가 실패하면 Errors 탭에 나타나지 않습니다. Claude Code는 해당 서버를 삭제하고 Invalid MCP server config for <server> in <path>만 해당 디버그 로그에 기록합니다. 플러그인을 로드하지 않고 항목을 찾으려면 플러그인 디렉토리에서 셸에서 claude plugin validate를 실행합니다. 이는 오류로 보고합니다. v2.1.281 이전에는 claude plugin validate가 .mcp.json을 확인하지 않았습니다.

서버가 `--plugin-dir`로 작동하지만 설치 후 실패

플러그인의 작성자이고 서버가 --plugin-dir로 소스 디렉토리에서 플러그인을 로드할 때 시작되지만 설치 후 실패합니다. Claude Code는 설치된 플러그인을 캐시로 복사하므로 소스 디렉토리에서만 작동하는 경로가 중단됩니다. ${CLAUDE_PLUGIN_ROOT}로 플러그인 내부의 경로를 작성합니다. 플러그인 디렉토리 외부에 도달하는 경로의 경우 플러그인이 참조하는 파일이 디렉토리 외부에서 찾을 수 없음을 참조합니다.

언어 서버가 시작되지 않거나 너무 많은 메모리를 사용하거나 잘못된 진단을 보고

코드 인텔리전스 플러그인을 설치했고 Claude가 진단을 보지 못하거나 언어 서버가 너무 많은 메모리를 사용하거나 실제가 아닌 오류를 보고합니다.

언어 서버가 시작되지 않음

플러그인은 별도로 설치하는 언어 서버 바이너리에 연결되고 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의 기본 제공 검색 도구에 의존합니다.

모노레포의 거짓 양성 진단

작업 공간에 대해 구성되지 않은 언어 서버는 내부 패키지에 대해 확인되지 않은 가져오기를 보고할 수 있습니다. Claude Code 측에서 수정할 것이 없으며 진단이 Claude가 코드를 편집하는 것을 중단하지 않습니다.

플러그인 만들기

플러그인을 개발 중이고 --plugin-dir로 로드하거나 로컬 마켓플레이스에서 설치합니다. 이러한 항목은 플러그인을 개발하는 동안 발생하는 실패를 다룹니다. 각 변경 후 확인을 실행하려면 테스트 및 디버그를 참조합니다. 플러그인의 사용자에게도 도달하는 두 가지 실패는 플러그인이 설치되었지만 작동하지 않음 아래에 항목이 있습니다:

발화하지 않는 훅: 발화하지 않는 훅을 참조합니다.
시작하지 않는 MCP 서버: 시작하지 않는 MCP 서버를 참조합니다.

`commands path not found: <path>`

Errors 탭은 commands path not found: <absolute path>를 Check that the path in your manifest or marketplace config is correct의 지침과 함께 표시합니다. 동일한 메시지는 skills, agents 및 hooks에 대해 나타납니다. Claude Code는 plugin.json 또는 마켓플레이스 항목의 경로를 플러그인 루트에 대해 확인했고 거기에 아무것도 찾지 못했습니다. 메시지의 경로는 확인한 절대 경로이므로 디스크의 내용과 비교합니다. 경로를 수정하거나 디렉터리를 만든 다음 /reload-plugins를 실행합니다.

v2.1.299 이전에는 이 메시지가 시작 시 synced[0]과 같은 태그로 레이블이 지정된 행에 나타날 수 있었습니다. 해당 행은 claude.ai에서 동기화된 플러그인을 위한 것입니다. 이 메시지는 머신의 다른 Claude Code 세션이 직전에 플러그인을 업데이트하고 파일을 이동했을 때 나타났습니다. 플러그인을 로드하려면 Claude Code를 다시 시작합니다. 이러한 이유로 메시지가 나타나지 않도록 하려면 v2.1.299 이상으로 업데이트합니다.

매니페스트의 경로는 플러그인 루트에 상대적이고 ./로 시작합니다. 플러그인 루트 외부로 확인되는 경로는 대신 <component> path escapes plugin directory로 보고되고 삭제됩니다.

`--plugin-dir` (마켓플레이스 루트에서 `plugins/` 아래의 플러그인을 로드하지 않음)

claude --plugin-dir <path>를 시작했고 오류가 없지만 플러그인의 스킬, 에이전트 및 훅이 없습니다. --plugin-dir은 .claude-plugin/plugin.json과 skills/ 같은 구성 요소 디렉터리를 포함하는 플러그인의 루트 디렉터리를 받습니다. 대신 마켓플레이스 루트를 가리키면 Claude Code가 marketplace.json을 읽지 않으므로 plugins/ 아래의 플러그인이 로드되지 않으며 오류가 없습니다. v2.1.281 이전에는 Claude Code가 마켓플레이스 루트를 해당 디렉터리의 이름을 따서 명명한 하나의 빈 플러그인으로 로드했습니다. 플래그를 플러그인 디렉터리 자체로 가리킵니다:

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

그런 다음 /plugin에서 Installed를 열어 플러그인의 세부 정보 창이 구성 요소를 나열합니다.

플러그인이 디렉터리 외부에서 참조하는 파일을 찾을 수 없음

플러그인은 --plugin-dir로 소스 디렉터리에서 작동하지만 설치 후 ../shared-utils와 같은 경로에 대한 오류로 실패합니다. Claude Code는 설치된 플러그인을 캐시로 복사하고 거기서 로드하므로 플러그인 자체의 디렉터리 외부에 도달하는 경로는 캐시에서 아무것도 가리키지 않습니다. 공유 파일을 플러그인 디렉터리 내부로 이동하거나 내부의 심볼릭 링크를 통해 참조합니다. 캐시가 있는 위치와 경로가 확인되는 방식은 디스크에서 플러그인 찾기를 참조합니다.

`${CLAUDE_PLUGIN_ROOT}`가 Windows에서 정방향 슬래시를 표시

Windows에서 Git Bash를 통해 실행되는 플러그인 훅은 C:\Users\you\... 대신 C:/Users/you/...로 ${CLAUDE_PLUGIN_ROOT}를 수신하고 백슬래시를 기대한 스크립트가 중단됩니다. Git Bash가 설치되어 있으면 셸 형식 훅은 기본적으로 Git Bash를 통해 실행됩니다. Git Bash를 통해 실행되는 훅의 경우 Claude Code는 Bash가 백슬래시를 이스케이프로 읽지 않도록 정방향 슬래시로 경로를 전달합니다. Bash 내장, MSYS 도구 및 기본 Windows 바이너리는 모두 해당 형식을 허용합니다. 스크립트에 백슬래시가 필요하면 exec 형식 및 셸 형식 아래에 설명된 기본 경로를 유지하는 형식 중 하나로 훅을 전환합니다:

args 배열로 프로세스를 직접 생성하는 exec 형식 훅
"shell": "powershell"이 있는 훅

플러그인이 로드되지만 스킬이 누락됨

플러그인이 Installed 아래에 오류 없이 나열되지만 /를 입력할 때 스킬이 제공되지 않습니다. 스킬은 플러그인 루트의 skills/에서 로드되고 명령은 플러그인 루트의 commands/에서 로드됩니다. .claude-plugin/ 내부에는 plugin.json만 속하고 .claude-plugin/ 내부의 skills/ 디렉터리는 스캔되지 않습니다. 디렉터리를 플러그인 루트로 이동하고 /reload-plugins를 실행합니다. 그 후 /plugin의 플러그인 세부 정보 창이 스킬을 나열하고 /를 입력하면 제공됩니다. 각 스킬은 SKILL.md를 포함하는 디렉터리입니다. 디렉터리가 아닌 SKILL.md 파일을 가리키는 매니페스트의 skills 항목은 path is a file; skills entries must be directories containing SKILL.md로 보고됩니다.

스킬이 로드되지만 Claude가 절대 스킬을 호출하지 않음

플러그인의 스킬은 /<plugin>:<skill> 명령을 입력할 때 실행되지만 Claude는 일반 요청에 응답하여 절대 호출하지 않습니다. 이 순서대로 이러한 원인을 확인합니다:

스킬이 disable-model-invocation: true를 설정: 첫 번째 플러그인 만들기의 템플릿 스킬이 설정합니다. Claude가 스스로 호출하기를 원하는 스킬에서 해당 줄을 제거합니다. 스킬을 호출할 수 있는 사람 제어는 필드를 다룹니다.
설명이 사람들이 요청하는 방식과 일치하지 않음: 스킬이 트리거되지 않음의 확인을 진행합니다.
설명이 잘림: 많은 스킬이 설치되면 Claude Code가 설명을 단축하여 목록의 문자 예산에 맞추고 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. 스킬 설명이 짧게 잘림을 참조합니다.

현실적인 프롬프트 전체에서 스킬이 얼마나 자주 트리거되는지 측정하려면 한 번에 하나씩 확인하는 대신 tool_used: Skill 채점자로 eval 경우를 작성하고 각 설명 변경 후 claude plugin eval로 실행합니다.

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

플러그인의 루트가 아닌 디렉터리(예: 홈 디렉터리 또는 플러그인을 하위 디렉터리에 유지하는 저장소의 루트)에서 claude plugin eval init을 실행했습니다. init은 작업 디렉터리 아래에 제품군을 작성하므로 플러그인이 절대 볼 수 없는 evals/ 디렉터리를 만드는 대신 중단됩니다. 플러그인의 루트(.claude-plugin/plugin.json 또는 스킬의 SKILL.md를 보유하는 디렉터리)로 변경하고 명령을 다시 실행합니다. 의도적으로 다른 곳에 제품군을 스캐폴드하려면 --eval-dir을 전달합니다. eval로 플러그인 테스트를 참조합니다.

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

플러그인이 userConfig 옵션을 선언하지만 설치할 때 구성 대화상자가 나타나지 않습니다. 설치가 값을 요청하는지 여부는 실행 위치에 따라 다릅니다:

세션의 /plugin install 또는 /plugin의 Discover 탭: 대화상자는 이 대화형 설치의 일부입니다.
VS Code 확장의 플러그인 관리 대화상자: 설정되지 않은 옵션을 설치 후 양식으로 요청합니다. 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.를 인쇄합니다. 설정되지 않은 옵션이 필수이면 (M required)가 not yet set을 따릅니다.

셸에서 설치한 경우 --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로 참조하는 번들은 설치 시간에 읽지 않으므로 해당 키는 나열되지 않으며 메시지는 /plugin에서 구성하도록 말합니다. <server>.<key> 키 설정에는 Claude Code v2.1.285 이상이 필요합니다.

`claude plugin validate`가 오류를 보고

claude plugin validate <path>를 실행했거나 세션에서 /plugin validate <path>를 실행했고 Found N errors 및 Validation failed를 인쇄한 다음 종료 코드 1로 종료했습니다. 검증자는 제공한 경로에서 매니페스트를 읽습니다: 플러그인 디렉터리의 경우 .claude-plugin/plugin.json, 마켓플레이스 디렉터리의 경우 .claude-plugin/marketplace.json, 둘 다 보유하는 디렉터리의 경우 둘 모두를 읽습니다. 마켓플레이스의 경우 항목 자체의 매니페스트의 문제를 항목 인덱스로 접두사로 붙입니다(예: plugins[1] plugin.json → json: ...). v2.1.289 이전에는 Claude Code가 둘 다 보유하는 디렉터리를 마켓플레이스로만 검증했습니다. 표는 유효성 검사를 중단하는 메시지와 두 가지 경고(No frontmatter block found 및 Unknown field '<key>')를 다룹니다. --strict를 전달할 때만 중단됩니다. 누락된 설명과 같은 다른 경고는 나열되지 않습니다.

메시지	원인	수정
`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`을 수정할 때까지 세션이 해당 파일의 훅 없이 플러그인을 로드합니다.
`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>`	스킬, 에이전트 또는 명령 파일에 누락되거나 유효하지 않은 YAML frontmatter가 있습니다.	`---` 구분 기호 사이에 frontmatter를 추가하거나 수정합니다. 플러그인 디렉터리를 검증할 때 보고됩니다.
`Plugin name "<name>" is reserved: it passes as one of Anthropic's own`	플러그인의 `name`은 예약된 이름 중 하나입니다.	플러그인이 수행하는 작업에 맞게 플러그인의 이름을 바꿉니다.
`Unknown field '<key>'`	매니페스트에 스키마가 정의하지 않는 필드가 있습니다.	제거하거나 메시지가 제안하는 이름을 사용합니다. Claude Code는 로드 시간에 알려지지 않은 필드를 무시합니다. `plugin.json`의 `privacyPolicyUrl` 및 기타 디렉터리 목록 필드는 디렉터리 목록 필드를 참조합니다.

각 수정 후 오류가 없을 때까지 명령을 다시 실행합니다. plugin.json 필드는 매니페스트 참조에 있고 마켓플레이스 수준 메시지는 마켓플레이스 유효성 검사 오류 아래에 있습니다.

`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에 추가하도록 합니다. 엄격한 모드를 참조합니다.

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

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

마켓플레이스 호스팅

마켓플레이스를 게시하고 사용자가 오류를 보고하거나 자신의 유효성 검사가 실패합니다. 이러한 항목은 마켓플레이스 소유자용입니다.

상대 경로가 있는 플러그인이 URL 기반 마켓플레이스에서 실패

사용자가 https://example.com/marketplace.json URL로 마켓플레이스를 추가했습니다. ./plugins/my-plugin과 같은 상대 경로인 source가 있는 플러그인의 설치가 its marketplace entry path does not stay inside the marketplace directory로 실패합니다. 이미 설치된 플러그인이 Plugin source path refused로 로드되지 못합니다. 두 메시지 모두 오류 참조 항목이 있습니다. 사용자가 URL 기반 마켓플레이스를 추가하면 Claude Code는 marketplace.json 파일 자체만 다운로드합니다. 해당 서버에서 상대 경로로 플러그인 파일을 가져오지 않으므로 항목의 상대 경로는 절대 가져오지 않은 디렉토리를 가리킵니다. 각 항목에 Claude Code가 자체적으로 가져올 수 있는 소스(예: GitHub 저장소)를 제공합니다:

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

또는 git 저장소에서 마켓플레이스를 호스팅하고 사용자에게 저장소 URL로 추가하도록 알립니다. git 소스의 경우 Claude Code가 전체 저장소를 클론하므로 상대 경로가 확인됩니다. 소스 유형은 마켓플레이스 참조에 있습니다.

git 서브모듈에 있는 루트 플러그인의 파일이 설치 후 누락됨

플러그인이 마켓플레이스 루트에 있으며 저장소의 git 서브모듈에 있는 파일을 실행하거나 읽습니다. 설치 후 서브모듈의 디렉토리가 비어 있습니다. v2.1.295 이전에는 Claude Code가 모든 서브모듈을 가져왔으므로 디렉토리가 채워져 있었습니다. Claude Code가 마켓플레이스를 클론할 때는 플러그인 파일을 포함하는 서브모듈만 가져옵니다. 루트에 있는 플러그인의 경우 플러그인 구성의 경로와 플러그인 파일의 텍스트를 읽어 판단합니다. 스크립트가 실행 중에 만들어 내는 경로는 인식할 수 없습니다. 서브모듈 내부를 가리키는 경로를 Claude Code가 읽을 수 있는 곳에 전체 형태로 작성합니다(예: 훅 명령의 ${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh). 그러면 Claude Code가 해당 플러그인에 대해 저장소의 모든 서브모듈을 가져옵니다.

마켓플레이스 유효성 검사 오류

마켓플레이스 디렉토리에서 claude plugin validate .를 실행했고 마켓플레이스 파일 자체에 오류 또는 경고를 보고했습니다. claude plugin validate는 또한 source가 로컬 경로인 각 항목을 검증하고 항목의 version이 플러그인 자체의 매니페스트와 불일치할 때 경고합니다. 표는 마켓플레이스 수준 메시지를 나열합니다. 항목 수준 메시지는 claude plugin validate 오류를 보고 아래의 플러그인 메시지이며 plugins[N] plugin.json →으로 접두사가 붙습니다.

메시지	종류	수정
`Duplicate plugin name "<name>" found in marketplace`	오류	각 플러그인에 고유한 `name`을 제공합니다.
`Path contains "..": <path>` (under `plugins[N].source`)	오류	`..` 세그먼트 없이 마켓플레이스 루트에 상대적인 경로를 사용합니다.
`Marketplace name cannot contain control or bidirectional-formatting characters`	오류	이름에서 문자(예: 이스케이프 또는 줄 바꿈)를 제거합니다.
`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`을 추가합니다.
`Plugin name "<name>" is not kebab-case` under `plugins[N] plugin.json → name`	경고	소문자, 숫자 및 하이픈으로 이름을 바꿉니다. claude.ai 마켓플레이스 동기화는 해당 형식을 요구합니다.
`Entry declares version "<a>" but <path>/plugin.json says "<b>"`	경고	항목을 `plugin.json`과 일치하도록 업데이트합니다. 이는 설치 시간에 권위 있습니다.
`Marketplace name "<name>" is reserved in Claude Desktop`	경고	마켓플레이스의 이름을 바꿉니다. Claude Desktop의 관리 마켓플레이스 동기화는 모든 대소문자에서 `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로만 보고되었습니다.

조직에 의해 차단됨

조직에서 플러그인을 제한하는 관리형 설정을 배포했으며, 정책 메시지와 함께 명령이 거부되었습니다. 이 항목들은 각 거부의 원인이 되는 설정을 알려 주므로 관리자에게 무엇을 요청해야 하는지 알 수 있습니다. 관리자 측 내용은 조직의 플러그인 관리를 참조하세요.

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

/plugin marketplace add, update 또는 설치를 실행했는데 Claude Code가 이 메시지와 함께 거부한 경우입니다. 관리자가 관리형 설정에서 blockedMarketplaces 또는 strictKnownMarketplaces를 설정했으며, 이 소스는 허용되지 않습니다. 관리자에게 해당 소스를 허용해 달라고 요청하거나, 메시지에 나열된 허용된 소스 중 하나를 추가하세요. 메시지의 나머지 부분을 확인하여 어떤 종류의 정책이 소스를 차단했는지 파악하세요.

Allowed sources: <list>: 차단이 blockedMarketplaces 차단 목록이 아니라 strictKnownMarketplaces 허용 목록에서 비롯된 것입니다
No external marketplaces are allowed.: strictKnownMarketplaces 허용 목록이 비어 있습니다
단축 표기가 github.com을 가정한다는 Tip:: 허용 목록이 호스트 이름으로 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가 표시되는 경우입니다. 마켓플레이스 소스를 차단하는 것과 동일한 관리형 설정이 로드 시점에도 적용됩니다. strictKnownMarketplaces에 이 마켓플레이스가 포함되어 있지 않거나 blockedMarketplaces에 이 마켓플레이스가 지정되어 있으므로, Claude Code는 해당 마켓플레이스와 그 플러그인의 로드를 중단합니다. 허용 목록의 경우 안내 메시지에 허용된 소스 또는 Contact your administrator to configure allowed marketplace sources가 표시됩니다. 차단 목록의 경우 This marketplace source is explicitly blocked by your administrator로 표시됩니다.

`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와 같이 이유를 명시하는 메시지와 함께 거부된 경우입니다. 관리형 설정이 이 플러그인, 해당 마켓플레이스 또는 플러그인에 필요한 의존성을 차단하고 있습니다. 관리자에게 어떤 항목이 적용되는지 문의하세요. 의존성이 차단된 경우, 해당 의존성의 마켓플레이스가 허용될 때까지 플러그인을 설치할 수 없습니다.

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

--plugin-dir, --plugin-url, --agents 또는 --mcp-config를 사용하여 claude를 시작했는데, Claude Code가 이 메시지와 Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved.를 표시하며 종료된 경우입니다. 관리자가 관리형 설정에서 disableSideloadFlags를 설정했으며, 이 설정은 임의의 경로에서 플러그인, 에이전트, 서버를 로드하는 플래그를 끕니다. 대신 승인된 마켓플레이스에서 플러그인을 로드하거나, 관리자에게 해당 설정을 제거해 달라고 요청하세요. /plugin Errors 탭의 관련 메시지로는 --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings가 있습니다. 관리형 설정이 해당 플러그인을 이름으로 활성화하거나 비활성화하고 있으며, 플래그가 정책을 재정의할 수 없도록 Claude Code는 --plugin-dir로 지정한 해당 플러그인의 사본을 무시합니다.

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

claude plugin init 또는 claude plugin enable을 실행했는데 이 메시지와 함께 중단된 경우입니다. 메시지는 strictKnownMarketplaces or blockedMarketplaces를 지정하며, 관리자에게 {"source":"skills-dir"}를 strictKnownMarketplaces에 추가하거나 blockedMarketplaces에서 제거해 달라고 요청하도록 안내합니다. skills-dir 소스는 Claude Code가 ~/.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는 시드로 관리되는 마켓플레이스를 읽기 전용으로 취급합니다. 일괄 marketplace update는 이 마켓플레이스를 건너뛰고 나머지를 업데이트합니다. 마켓플레이스의 콘텐츠를 변경하려면 시드 이미지를 유지 관리하는 담당자에게 업데이트를 요청하세요. 절차는 시드 컨테이너 및 CI를 참조하세요.

다음 단계

플러그인 로딩 참조: 범위, 캐시 및 우선순위가 작동하는 방식
플러그인 명령 참조: claude plugin 명령의 플래그, 기본값, 출력 및 종료 코드
플러그인 설치 및 관리: 시작부터 설치 단계
조직의 플러그인 관리: 관리자를 위한 정책 측 문제 해결

​/plugin이 실행되는 위치 찾기

​/plugin isn't available in this environment

​zsh: no such file or directory: /plugin

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

​claude: command not found after claude plugin ...

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

​마켓플레이스 추가

​Marketplace "claude-plugins-official" not found

​Marketplace "<name>" not found

​Invalid marketplace source format

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

​Invalid git URL

​Path does not exist: <path>

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

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

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

​SSH authentication failed 또는 HTTPS authentication failed

​SSH host key is not in your known_hosts file

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

​Git clone timed out after 120s

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

​GitHub Enterprise Server 호스트에서 마켓플레이스 추가 실패

​플러그인 설치

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

​새로고침 힌트가 있는 not found in marketplace

​힌트가 없는 not found in marketplace

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

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

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

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

​Plugin archive integrity check failed

​An npm plugin source must name a registry package

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

​Marketplace "<name>" is added but ignored

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

​Plugin directory not found at path: <path>

​No plugins available 또는 No marketplaces configured

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

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

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

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

​의존성 오류

​플러그인이 설치되었지만 작동하지 않음

​플러그인이 나타나지 않거나 스킬이 표시되지 않음

​Run /reload-plugins to apply.

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

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

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

​installed_plugins.json could not be read and was rebuilt

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

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

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

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

​Windows에서 plugin uninstall 후에도 플러그인이 설치된 상태로 남음

​git 저장소에서 설치한 플러그인의 버전이 unknown으로 표시됨

​Failed to load hooks from <path> 및 발화하지 않는 훅

​훅이 로드되지 못함

​트랜스크립트의 hook error 공지

​플러그인 훅이 도구 호출 또는 프롬프트를 차단

​훅이 로드되지만 절대 발화하지 않음

​Plugin directory does not exist: <path>

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

​Invalid MCP server config for "<server>": <error>

​Bundled MCP server "<name>" was not started: it needs configuration

​서버가 구성되었지만 절대 연결되지 않음

​서버가 --plugin-dir로 작동하지만 설치 후 실패

​언어 서버가 시작되지 않거나 너무 많은 메모리를 사용하거나 잘못된 진단을 보고

​언어 서버가 시작되지 않음

​언어 서버가 너무 많은 메모리를 사용

​모노레포의 거짓 양성 진단

​플러그인 만들기

​commands path not found: <path>

​--plugin-dir (마켓플레이스 루트에서 plugins/ 아래의 플러그인을 로드하지 않음)

​플러그인이 디렉터리 외부에서 참조하는 파일을 찾을 수 없음

​${CLAUDE_PLUGIN_ROOT}가 Windows에서 정방향 슬래시를 표시

​플러그인이 로드되지만 스킬이 누락됨

​스킬이 로드되지만 Claude가 절대 스킬을 호출하지 않음

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

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

​claude plugin validate가 오류를 보고

`/plugin`이 실행되는 위치 찾기

`/plugin isn't available in this environment`

`zsh: no such file or directory: /plugin`

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

`claude: command not found` after `claude plugin ...`

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

마켓플레이스 추가

`Marketplace "claude-plugins-official" not found`

`Marketplace "<name>" not found`

`Invalid marketplace source format`

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

`Invalid git URL`

`Path does not exist: <path>`

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

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

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

`SSH authentication failed` 또는 `HTTPS authentication failed`

`SSH host key is not in your known_hosts file`

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

`Git clone timed out after 120s`

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

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

플러그인 설치

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

새로고침 힌트가 있는 `not found in marketplace`

힌트가 없는 `not found in marketplace`

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

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

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

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

`Plugin archive integrity check failed`

`An npm plugin source must name a registry package`

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

`Marketplace "<name>" is added but ignored`

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

`Plugin directory not found at path: <path>`

`No plugins available` 또는 `No marketplaces configured`

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

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

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

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

의존성 오류

플러그인이 설치되었지만 작동하지 않음

플러그인이 나타나지 않거나 스킬이 표시되지 않음

`Run /reload-plugins to apply.`

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

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

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

`installed_plugins.json could not be read and was rebuilt`

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

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

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

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

Windows에서 `plugin uninstall` 후에도 플러그인이 설치된 상태로 남음

git 저장소에서 설치한 플러그인의 버전이 `unknown`으로 표시됨

`Failed to load hooks from <path>` 및 발화하지 않는 훅

훅이 로드되지 못함

트랜스크립트의 `hook error` 공지

플러그인 훅이 도구 호출 또는 프롬프트를 차단

훅이 로드되지만 절대 발화하지 않음

`Plugin directory does not exist: <path>`

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

`Invalid MCP server config for "<server>": <error>`

`Bundled MCP server "<name>" was not started: it needs configuration`

서버가 구성되었지만 절대 연결되지 않음

서버가 `--plugin-dir`로 작동하지만 설치 후 실패

언어 서버가 시작되지 않거나 너무 많은 메모리를 사용하거나 잘못된 진단을 보고

언어 서버가 시작되지 않음

언어 서버가 너무 많은 메모리를 사용

모노레포의 거짓 양성 진단

플러그인 만들기

`commands path not found: <path>`

`--plugin-dir` (마켓플레이스 루트에서 `plugins/` 아래의 플러그인을 로드하지 않음)

플러그인이 디렉터리 외부에서 참조하는 파일을 찾을 수 없음

`${CLAUDE_PLUGIN_ROOT}`가 Windows에서 정방향 슬래시를 표시

플러그인이 로드되지만 스킬이 누락됨

스킬이 로드되지만 Claude가 절대 스킬을 호출하지 않음

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

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

`claude plugin validate`가 오류를 보고