> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 플러그인 문제 해결

> Claude Code에서 플러그인 오류를 수정합니다. /plugin이 실행되는 단계부터 설치 및 조직 정책까지 단계별로 그룹화된 정확한 메시지를 찾습니다.

이 페이지는 Claude Code 플러그인 및 마켓플레이스(Claude Code가 플러그인을 설치하는 카탈로그)의 오류 메시지 및 증상을 나열합니다. 각 항목은 원인, 한 가지 해결 방법, 그리고 해결 방법이 작동한 후 표시되는 내용을 제공합니다.

메시지가 플러그인 또는 마켓플레이스의 이름을 지정하는 경우, 항목은 `<name>` 같은 자리 표시자를 표시합니다.

플러그인을 설치하거나, 빌드하거나, 마켓플레이스를 호스팅하거나, 조직의 플러그인을 관리하는지 여부에 관계없이 이 페이지를 사용합니다.

> [!NOTE]
>
> 이러한 경우는 다른 페이지에서 다룹니다:
>
> * **범위, 캐시 및 우선순위가 작동하는 방식**: [플러그인 로딩 참조](https://code.claude.com/docs/ko/plugins/loading.md)를 읽습니다.
> * **플래그, 필드 또는 명령 조회**: [플러그인 명령 참조](https://code.claude.com/docs/ko/plugins/cli-reference.md), [매니페스트 참조](https://code.claude.com/docs/ko/plugins/manifest-reference.md) 또는 [마켓플레이스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md)를 사용합니다.
> * **`hooks module not loaded` 또는 `hooks module did not load` 메시지**: 해당 플러그인은 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)이므로 [mod가 로드되지 않음](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#the-mod-doesn’t-load)을 읽습니다.

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

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

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

### `/plugin isn't available in this environment`

Claude Code 터미널 세션이 아닌 다른 곳에서 `/plugin`을 입력했고, Claude가 아무것도 열지 않고 이 줄로 응답했습니다.

`/plugin` 패널을 그릴 터미널이 없는 세션에서 이 응답을 받습니다: `claude -p`를 사용한 [비대화형 모드](https://code.claude.com/docs/ko/headless.md), Agent SDK, Claude 데스크톱 앱의 Code 탭, VS Code 확장 패널, 그리고 claude.ai/code의 브라우저.

VS Code 확장 패널에서는 `/plugin install <plugin>@<marketplace>`와 같이 그 뒤에 무언가가 있는 `/plugin` 줄만 이 응답을 받습니다. 혼자 입력한 `/plugin` 또는 `/plugins`는 **플러그인 관리** 대화상자를 엽니다.

대신 사용 중인 표면에서 플러그인을 설치합니다:

* **Claude 데스크톱 앱, 로컬 또는 SSH 세션**: [플러그인 설치](https://code.claude.com/docs/ko/plugins/install.md#install-a-plugin) 아래의 **데스크톱 앱** 탭을 사용합니다.
* **VS Code 확장**: [플러그인 설치](https://code.claude.com/docs/ko/plugins/install.md#install-a-plugin) 아래의 **VS Code** 탭을 사용합니다.
* **웹의 Claude Code 또는 데스크톱 클라우드 세션**: 클라우드 세션에는 플러그인 브라우저가 없습니다. 클라우드 세션이 로드하는 내용은 [플러그인 설치](https://code.claude.com/docs/ko/plugins/install.md#install-a-plugin)의 **클라우드 세션** 탭을 참조합니다.
* **액세스 권한이 있는 터미널**: `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 세션 내에서 입력하는 명령입니다. 세션을 시작하고 거기서 동일한 명령을 입력합니다:

```shell theme={null}
claude
```

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

```text theme={null}
/plugin install <plugin>@<marketplace>
```

성공적인 설치는 `✓ Installed <plugin>.`로 시작하는 요약을 인쇄합니다. 설치 자체가 실패하면 해당 메시지는 [마켓플레이스 추가](#add-a-marketplace) 또는 [플러그인 설치](#install-a-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는 [자신의 형태의 이 오류](#zsh-no-such-file-or-directory-plugin)를 보고합니다.

대신 다음 중 하나를 사용합니다:

* `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 확인](https://code.claude.com/docs/ko/troubleshoot-install.md#verify-your-path)을 따른 다음 플러그인 명령을 재시도합니다.

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

어딘가에서 본 플러그인 명령을 입력했고 세션에서 `Unknown command: /<name>`을 받았거나, 셸의 `claude` 바이너리에서 `error: unknown command '<name>'` 또는 `error: unknown option '<flag>'`를 받았습니다.

Claude Code가 없는 여러 명령 철자가 사용 중입니다. 아래 표는 각각을 실제 명령에 매핑합니다. [플러그인 명령 참조](https://code.claude.com/docs/ko/plugins/cli-reference.md)는 하위 명령과 해당 플래그를 나열합니다.

| 입력한 내용 | 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` 셸 명령은 절대 등록하지 않습니다.

추가한 다음 설치를 다시 시도합니다:

```text theme={null}
/plugin marketplace add anthropics/claude-plugins-official
```

Claude Code는 `Successfully added marketplace: claude-plugins-official`을 인쇄하고, `/plugin marketplace list`는 소스와 함께 마켓플레이스를 표시합니다.

이 메시지의 다른 마켓플레이스 이름의 경우 [`Marketplace "<name>" not found`](#marketplace-not-found)를 참조합니다.

동일한 문자열은 `/plugin` **Errors** 탭, 로드 실패 목록인 패널에도 나타나며, 설정에 나열된 플러그인이 추가하지 않은 마켓플레이스의 이름을 지정할 때입니다.

### `Marketplace "<name>" not found`

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

* **`/plugin install <plugin>@<name>`**: 설치 줄, 종종 누군가가 보낸 줄에서 추가하지 않은 마켓플레이스의 이름을 지정합니다. 이 항목의 나머지 부분은 찾기 및 추가를 다룹니다.
* **`/plugin install <source>` (경로, URL 또는 `owner/repo` 포함)**: 이 형식은 이미 추가한 소스에 대해서도 설치하는 대신 메시지를 보고합니다. 한 명령에서 소스에서 설치하려면 [마켓플레이스 추가 및 한 명령에서 설치](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace-and-install-in-one-command)를 참조합니다.

이름이 `claudeai-`로 시작하면 마켓플레이스가 claude.ai에서 호스팅되며, 셸에서 `claude plugin marketplace add --claudeai <name>`으로 이름으로 추가합니다. [claude.ai에서 마켓플레이스 추가](https://code.claude.com/docs/ko/plugins/install.md#add-from-claude-ai)를 참조합니다.

다른 이름의 경우, 설치 줄은 마켓플레이스의 이름을 지정하지만 마켓플레이스가 호스팅되는 위치를 말하지 않으며, Claude Code는 마켓플레이스 이름을 조회할 인덱스가 없습니다. 줄을 보낸 사람에게 마켓플레이스의 소스(GitHub `owner/repo`, git URL 또는 경로)를 요청합니다. 그런 다음 [마켓플레이스를 추가](https://code.claude.com/docs/ko/plugins/install.md#add-a-marketplace)하고 설치 줄을 다시 실행합니다.

누군가가 보낸 마켓플레이스는 타사이므로 [설치하기 전에 플러그인을 검토](https://code.claude.com/docs/ko/plugins/security.md#review-a-plugin-before-you-install)합니다.

이미 마켓플레이스를 추가한 경우 `/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`과 같은 단순 호스트명도 마찬가지입니다.

소스를 허용된 형식 중 하나로 다시 입력합니다:

```text theme={null}
/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로 추가하려면 세션에서:

```text theme={null}
/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`라고 말하는 거부는 조직의 설정에서 나옵니다. [마켓플레이스 소스가 엔터프라이즈 정책에 의해 차단됨](#marketplace-source-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`이며, [마켓플레이스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md)는 허용된 위치를 나열합니다.

수정은 소유자와 다른 모든 사람에게 다릅니다:

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

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

마켓플레이스를 추가했는데, 해당 `marketplace.json`의 [`name`](https://code.claude.com/docs/ko/plugins/marketplace-reference#top-level-fields)이 `my-plugin@my-marketplace`와 같은 [플러그인 id](https://code.claude.com/docs/ko/plugins/loading.md#find-where-a-plugin-came-from)에서 `@` 뒤에 오는 부분으로 유효하지 않습니다. Claude Code는 추가를 거부하고 아무것도 등록하지 않습니다.

메시지의 나머지 부분은 이름에 대한 규칙을 설명합니다. 이 예에서 `_internal`은 `_`로 시작하므로 규칙을 위반합니다:

```text theme={null}
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`](https://code.claude.com/docs/ko/plugins/marketplace-reference#top-level-fields)이 `constructor`, `toString`, `valueOf`와 같이 모든 JavaScript 객체가 가진 멤버 이름 중 하나입니다. Claude Code는 이러한 이름을 예약해 두므로 추가를 거부하고 아무것도 등록하지 않습니다. [예약된 이름](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#reserved-names)에 해당 이름이 나열되어 있습니다.

이 예에서 마켓플레이스의 이름은 `constructor`입니다:

```text theme={null}
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`](https://code.claude.com/docs/ko/settings-reference#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로 폴백합니다.

백그라운드 자동 업데이트가 자격 증명으로 수행할 수 있는 작업과 수행할 수 없는 작업은 [백그라운드 자동 업데이트가 자격 증명으로 수행하는 작업](https://code.claude.com/docs/ko/plugins/host-marketplace.md#what-background-auto-update-does-with-credentials)을 참조합니다.

### `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`로 클론하므로 키를 자동으로 수락하는 대신 아직 수락하지 않은 호스트를 거부합니다. 터미널에서 한 번 연결하여 지문을 수락한 다음 다시 시도합니다:

```shell theme={null}
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을 설치하고 다시 시도합니다:

**1. Windows용 Git 설치**

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

**2. 새 터미널 열기**

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

**3. git이 실행되는지 확인**

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

**4. 추가 다시 시도**

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

### `Git clone timed out after 120s`

마켓플레이스를 추가하거나 업데이트했고 `Git clone timed out after 120s`로 실패했으며, `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`를 설정하는 힌트가 뒤따릅니다.

마켓플레이스 클론 및 업데이트를 위해 다시 클론하면 기본적으로 120초가 소요됩니다. 큰 저장소 또는 느린 연결의 경우 제한을 높입니다. 값은 밀리초 단위입니다:

> [tab] Bash 또는 Zsh
>
> ```bash theme={null}
> export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000
> ```

> [tab] PowerShell
>
> ```powershell theme={null}
> $env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"
> ```

그런 다음 동일한 셸에서 다시 시도합니다.

저장소가 모노레포인 경우 `claude plugin marketplace add <source> --sparse <paths>`로 이름을 지정하는 디렉토리로 체크아웃을 제한합니다.

저장소에 큰 git 서브모듈이 있는 경우 Claude Code를 업데이트합니다. v2.1.295 이상에서는 Claude Code가 [플러그인 파일이 있는 서브모듈](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository)만 가져옵니다. 이전 버전은 모든 서브모듈을 가져오며, 이것만으로도 120초를 모두 소진할 수 있습니다.

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

마켓플레이스의 git 호스트에 도달할 수 없는 환경에서 작업하고 있으며, 모든 세션이 백그라운드에서 실패한 새로고침을 반복합니다. 마켓플레이스의 기존 체크아웃은 제자리에 남아 있고 시작이 지연되지 않습니다.

각 세션에서 [자동 업데이트가 켜진](https://code.claude.com/docs/ko/plugins/loading.md#which-marketplaces-and-plugins-auto-update) 마켓플레이스의 경우 Claude Code는 백그라운드에서 마켓플레이스의 git 호스트에서 새 커밋을 확인합니다. 해당 확인이 호스트에 도달할 수 없으면 마켓플레이스를 다시 클론하려고 시도하고 오프라인에서 해당 클론도 실패합니다.

호스트에 도달할 수 없을 때 다시 클론 시도를 건너뛰고 기존 체크아웃을 계속 사용하려면 이 변수를 설정합니다:

> [tab] Bash 또는 Zsh
>
> ```bash theme={null}
> export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
> ```

> [tab] PowerShell
>
> ```powershell theme={null}
> $env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"
> ```

변수가 설정되면 Claude Code는 이미 `.claude-plugin/marketplace.json`을 포함하는 체크아웃에 대해서만 다시 클론을 건너뜁니다. 클론되지 않았거나 클론이 중간에 중단된 마켓플레이스는 여전히 클론 시도를 받으므로 온라인 상태에서 한 번 추가합니다.

완전히 오프라인 배포의 경우 [컨테이너 및 CI 시드](https://code.claude.com/docs/ko/plugins/org.md#seed-containers-and-ci)를 따르는 `CLAUDE_CODE_PLUGIN_SEED_DIR`을 사용하여 이미지 빌드 시간에 플러그인 디렉토리를 미리 채웁니다.

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

GitHub Enterprise Server (GHES) URL에서 마켓플레이스를 추가했고 정책 오류를 받았거나, claude.ai에서 추가했고 GitHub 액세스 오류를 받았습니다.

두 경우 모두 GHES 페이지에 있습니다:

* [정책 오류](https://code.claude.com/docs/ko/github-enterprise-server.md#marketplace-add-fails-with-a-policy-error)는 조직이 마켓플레이스 소스를 제한했고 관리자가 호스트에 대한 `hostPattern`을 추가해야 함을 의미합니다.
* [claude.ai의 GitHub 액세스 오류](https://code.claude.com/docs/ko/github-enterprise-server.md#marketplace-add-on-claude-ai-fails-with-a-github-access-error)는 자신의 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`로 응답하면 먼저 [마켓플레이스를 추가](#add-a-marketplace)합니다.

#### 새로고침 힌트가 있는 `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가 조회 전에 마켓플레이스를 새로고침하지 않았습니다(예: 오프라인 상태일 때). 카탈로그 사본이 오래되었을 수 있습니다. 마켓플레이스 이름으로 새로고침한 다음 다시 설치합니다:

```text theme={null}
/plugin marketplace update <marketplace>
```

`claude plugin marketplace update`는 `Successfully updated marketplace: <name>`을 인쇄하고, `/plugin marketplace update`는 `✔ Updated 1 marketplace`을 표시합니다. 재시도된 설치가 동일한 메시지를 인쇄하면 [`not found in marketplace` (힌트 없음)](#the-message-has-no-hint)에서 설명하는 대로 이름을 확인합니다. [Claude Code가 설치 전에 마켓플레이스를 새로고침할 때](https://code.claude.com/docs/ko/plugins/loading.md#when-claude-code-refreshes-a-marketplace-before-an-install)는 새로고침이 실행되지 않는 다른 경우를 나열합니다.

#### 힌트가 없는 `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가 조회 전에 새로고침합니다:

```text theme={null}
/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`를 생략합니다.

플러그인은 이미 모든 프로젝트에서 사용 가능하므로 추가할 것이 없습니다. [범위](https://code.claude.com/docs/ko/plugins/install.md)를 변경하거나 활성화 또는 비활성화하거나 구성하려면 `/plugin`을 열고 **Installed**로 이동합니다.

프로젝트 또는 로컬 범위에만 설치된 플러그인은 이 메시지를 트리거하지 않습니다. Claude Code를 사용하면 사용자 범위에서도 설치할 수 있으므로 다른 프로젝트에서 사용할 수 있습니다.

셸의 `claude plugin install`은 다른 메시지를 인쇄합니다. 대상 범위에 이미 설치된 플러그인의 경우 `Plugin "<name>@<marketplace>" is already installed (scope: user)`를 인쇄하고 종료 코드 0으로 종료합니다. 캐시 디렉토리가 누락된 경우 동일한 명령이 다시 다운로드합니다.

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

`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`의 제거 단계를 지정합니다. 실행한 다음 다시 설치합니다. 제거가 제거하는 것에 대해서는 [제거가 삭제하고 유지하는 것](https://code.claude.com/docs/ko/plugins/cli-reference.md#what-an-uninstall-deletes-and-keeps)을 참조합니다.
* **두 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를 업데이트한 다음 설치를 다시 시도합니다. 소스 유형은 [마켓플레이스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md)에 있습니다.

### `Plugin archive integrity check failed`

zip 아카이브로 배포되는 플러그인을 설치했고, Claude Code가 이 줄과 `The archive was not installed.`로 거부했습니다. 플러그인의 마켓플레이스 항목은 `sha256` 핀이 있는 [`archive` 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference)를 사용하고, 다운로드된 파일의 다이제스트가 핀과 일치하지 않습니다.

전체 메시지는 다음과 같습니다:

```text theme={null}
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` 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference#npm-plugin-source)를 사용하는 플러그인이 설치, 업데이트 또는 로드에 실패했으며, 메시지에 이 문장이 포함되어 있습니다. Claude Code는 아무것도 가져오기 전에 항목의 `package` 값을 확인하고 거부했습니다. 메시지는 값과 이유를 지정합니다:

```text theme={null}
"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 플러그인 소스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#npm-plugin-source)가 허용하는 값으로 변경하거나, 항목을 `github`, `url` 또는 `git-subdir` 소스로 전환합니다.
* **본인이 소유자가 아닌 경우**: 메시지를 마켓플레이스 소유자에게 보고합니다.

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

이전에 추가한 마켓플레이스가 로드를 중단했고 해당 플러그인도 마찬가지입니다. 이 줄은 `/plugin` **Errors** 탭 또는 다음 새로고침에 나타납니다.

마켓플레이스는 [공식 Anthropic 마켓플레이스용으로 예약된](https://code.claude.com/docs/ko/plugins/marketplace-reference.md) 이름으로 등록되어 있지만 등록된 소스는 `anthropics` GitHub 저장소가 아닙니다. 예약된 이름은 마켓플레이스가 로드되거나 새로고침될 때마다 다시 확인되므로 마켓플레이스와 설치된 플러그인이 로드를 중단합니다.

전체 메시지는 예약된 이름과 수정을 지정합니다:

```text theme={null}
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`는 영향을 받는 각 플러그인을 이유와 수정 방법을 지정하는 줄과 함께 보고합니다:

```text theme={null}
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`](https://code.claude.com/docs/ko/settings-reference#extraknownmarketplaces) 선언과 일치하지 않습니다.

이유 대신 `(see the debug log)`가 `is added but ignored` 뒤에 오면 Claude Code가 마켓플레이스의 이름을 거부한 것입니다(예: [예약된 이름의 다른 철자](https://code.claude.com/docs/ko/errors.md#marketplace-name-is-another-spelling-of-a-reserved-name)). [디버그 로그](https://code.claude.com/docs/ko/debug-your-config.md)에 해당 항목이 표시됩니다.

**수행할 작업:**

* 메시지의 수정 방법을 따릅니다. 셸에서 `claude plugin marketplace remove <name>`을 실행한 다음, 지원되는 소스 또는 로컬 경로에서 마켓플레이스를 다시 추가하고 해당 플러그인을 다시 설치합니다. remove 명령은 이 플러그인들을 제거합니다. remove 명령은 무시된 항목에도 작동합니다.
* 네트워크 위치의 마켓플레이스를 유지하려면 사용자 또는 관리형 설정의 [`extraKnownMarketplaces`](https://code.claude.com/docs/ko/settings-reference#extraknownmarketplaces) 아래에 선언합니다. 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 선언은 인정되지 않습니다.
* 설정 선언과 다른 소스의 경우 선언된 소스에서 마켓플레이스를 다시 추가하거나 선언을 변경합니다. `claude plugin marketplace add`도 같은 불일치를 거부합니다. [해당 `Cannot add marketplace` 항목](#cannot-add-marketplace-source-doesnt-match)을 참조합니다.
* 거부된 이름의 경우 마켓플레이스를 제거합니다. 줄에 `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`을 추가합니다:

```text theme={null}
/plugin marketplace add anthropics/claude-plugins-official
```

Claude Code는 `Successfully added marketplace: claude-plugins-official`을 인쇄하고 **Discover**는 해당 플러그인을 나열합니다. [Anthropic 마켓플레이스](https://code.claude.com/docs/ko/plugins/anthropic-marketplaces.md) 페이지는 추가할 수 있는 다른 마켓플레이스를 나열합니다.

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

세션 또는 셸에서 [설치 명령의 `--marketplace <source>`](https://code.claude.com/docs/ko/plugins/install#add-a-marketplace-and-install-in-one-command)로 새 마켓플레이스 소스를 지정했습니다. Claude Code가 해당 소스에서 가져온 카탈로그가 다른 소스에서 이미 추가한 마켓플레이스와 동일한 이름을 가지고 있습니다. Claude Code는 기존 마켓플레이스를 대체하지 않고 유지하며 플러그인은 설치되지 않습니다.

전체 메시지는 다음과 같습니다:

```text theme={null}
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`](https://code.claude.com/docs/ko/settings-reference#extraknownmarketplaces) 항목이 사용자 설정 또는 관리형 설정에 이미 있습니다. 지정한 소스가 해당 항목에 나열된 소스와 다르므로 Claude Code는 추가를 거부하고 아무것도 등록하지 않습니다.

두 소스는 유형이 같고 모든 필드의 값이 같을 때 일치합니다. 전달하지 않은 `ref`를 설정하는 항목은 다른 것으로 간주됩니다. `github` 항목은 저장소를 `https://github.com/` URL로 지정한 경우에도 다른 것으로 간주됩니다. Claude Code가 해당 URL을 [`git` 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference#marketplace-sources)로 기록하기 때문입니다. 다음 중 하나를 수행합니다:

* **선언된 소스 사용**: Claude Code는 [설정에 선언된 마켓플레이스를 자동으로 등록](https://code.claude.com/docs/ko/settings-reference.md#extraknownmarketplaces)하므로 먼저 세션에서 `/plugin marketplace list`를 실행합니다. 목록에 이름이 표시되면 마켓플레이스가 이미 등록된 것이므로 추가할 것이 없습니다.

  목록에 표시되지 않으면 항목에 작성된 방식대로 소스를 입력하여 추가합니다. `source` 객체가 `{ "source": "github", "repo": "acme-corp/claude-plugins", "ref": "v1.2.0" }`인 항목의 경우 다음을 실행합니다:

  ```text theme={null}
  /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)`였습니다.

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

`/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는 파일의 새 사본을 다운로드하고 [플러그인 캐시](https://code.claude.com/docs/ko/plugins/loading.md#find-plugins-on-disk)의 해당 버전 폴더로 이동합니다. 이 메시지는 이동이 실패했음을 의미하며, 일반적으로 설치가 실행되는 동안 다른 프로그램이 폴더를 사용하고 있기 때문입니다. 파일 시스템 코드는 괄호에 나타납니다:

```text theme={null}
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는 문제를 해결할 때까지 영향을 받는 플러그인을 비활성화된 상태로 유지합니다.

표는 각 메시지와 수정을 나열합니다. 작성자로서 의존성을 선언하려면 [플러그인 의존성](https://code.claude.com/docs/ko/plugins/dependencies.md)을 참조합니다.

| 메시지 | 의미 | 해결 방법 |
| :- | :- | :- |
| `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`입니다.

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

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

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

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

변경하기 전에 플러그인의 상태를 확인합니다:

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

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

**2. Errors 탭 읽기**

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

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

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

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

* **빌드 중인 플러그인**: [플러그인이 로드되지만 스킬이 누락됨](#plugin-loads-but-its-skills-are-missing)을 참조합니다.
* **다른 사람이 게시한 플러그인**: `/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가 설치 중에 플러그인을 활성화하지 않았습니다. 활성화하면 [프롬프트 캐시가 무효화](https://code.claude.com/docs/ko/prompt-caching.md#enabling-or-disabling-a-plugin)되거나 활성화 시도가 실패했기 때문입니다.

명령을 입력할 필요가 없습니다. 패널이 닫히고 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`에서 플러그인을 업데이트합니다.

  ```shell theme={null}
  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>`는 설치 디렉토리가 누락되었지만 기록이 존재하는 플러그인을 다시 다운로드합니다:

```shell theme={null}
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`로 Claude Code를 업데이트합니다.
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`](https://code.claude.com/docs/ko/settings-reference#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`](https://code.claude.com/docs/ko/settings-reference#cleanupperioddays) 일정에 따라 만료됩니다.

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

명령은 작동했습니다. 경고에 명시된 설정 파일에 오류가 있으므로, 이를 수정할 때까지 Claude Code는 명령이 해당 파일에 기록한 내용을 포함하여 파일 전체를 무시합니다.

경고에 명시된 오류를 수정합니다. Claude Code가 허용하지 않는 값의 경우 [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)에서 방법을 설명합니다. 그런 다음 명령의 변경 사항이 더 이상 파일에 없으면 명령을 다시 실행합니다.

이 경고는 셸에서 실행한 `claude plugin install`, `enable`, `disable` 또는 `claude plugin marketplace add`의 성공 줄 다음에 표시됩니다:

```text theme={null}
⚠ /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가 허용하지 않는 값이 있습니다. 허용되는 값은 [설정 참조](https://code.claude.com/docs/ko/settings-reference.md)에서 해당 설정을 찾아 확인합니다. 둘 이상의 값이 실패하면 텍스트는 `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`로 설정합니다. 이는 프로젝트 파일보다 우선순위가 높습니다. 메시지가 이름을 지정할 수 있는 다른 소스의 경우 [사용자 설정에서 비활성화되었지만 여전히 로드됨](https://code.claude.com/docs/ko/plugins/loading.md#disabled-in-user-settings-but-still-loads)을 참조합니다.

`claude plugin list`가 대신 플러그인을 `required by your org`로 표시하면 설정 파일이 관련되지 않습니다: 조직이 claude.ai에서 동기화된 플러그인을 필수로 표시하고 이전에 비활성화했더라도 로드됩니다. [claude.ai에서 동기화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)을 참조합니다.

### `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는 직접 설치할 때까지 다운로드하지 않습니다. 지침 줄의 명령을 셸에서 실행한 다음 다시 로드합니다:

```shell theme={null}
claude plugin install <name>@<marketplace> --scope project
```

세션에서 `/reload-plugins`를 실행한 후 **Errors** 탭 항목이 사라지고 플러그인이 **Installed** 아래에 나열됩니다.

조직이 플러그인을 미리 설치하면 대신 관리 설정을 통해 그렇게 합니다. [플러그인 사전 설치 및 필수](https://code.claude.com/docs/ko/plugins/org.md#pre-install-and-require-plugins)를 참조합니다.

### 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`로 동일한 제거 명령을 다시 실행합니다. 두 번째 실행은 자체 경로 표기 아래에서 기록을 찾지 못하므로 다른 표기 아래의 기록을 제거합니다. 프로젝트 범위 설치의 경우:

```shell theme={null}
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` 줄로 바꿉니다:

**1. Claude Code 업데이트**

[Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.302 이상으로 만듭니다. 이 버전은 커밋을 읽을 수 있는 형식으로 클론합니다:

```shell theme={null}
claude update
```

**2. 마켓플레이스 업데이트**

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

```shell theme={null}
claude plugin marketplace update my-marketplace
```

**3. 플러그인 업데이트**

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

```shell theme={null}
claude plugin update formatter@my-marketplace
```

**4. 버전 확인**

`Version:` 줄에 [12자 커밋 ID](https://code.claude.com/docs/ko/plugins/loading.md#how-claude-code-computes-the-version)와 같은 값이 있는지 확인합니다:

```shell theme={null}
claude plugin list
```

`claude plugin update`는 [실행할 때마다 한 범위의 블록을 변경](https://code.claude.com/docs/ko/plugins/cli-reference.md#which-scope-the-command-updates)합니다. 여전히 `unknown`이 표시되는 블록의 경우 해당 블록의 `Scope:` 값으로 다시 실행합니다:

```shell theme={null}
claude plugin update formatter@my-marketplace --scope project
```

다시 실행한 후에도 블록에 여전히 `unknown`이 표시되면 [추가 도움 받기](https://code.claude.com/docs/ko/troubleshooting.md#get-more-help)를 참조합니다.

### `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](https://code.claude.com/docs/ko/errors.md#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 형식](https://code.claude.com/docs/ko/hooks.md#exec-form-and-shell-form)을 사용합니다. 따옴표 없는 변수를 찾으려면 플러그인 디렉토리에서 `claude plugin validate`를 실행하고 [따옴표 경고](https://code.claude.com/docs/ko/plugins/manifest-reference.md#quoting-and-path-separators)를 찾습니다.

공지가 `Failed to run: Plugin directory does not exist: <path>`로 표시되면 [`Plugin directory does not exist`](#plugin-directory-does-not-exist)를 참조합니다.

다른 오류의 경우 플러그인 디렉토리에서 훅의 명령을 직접 실행하여 전체 출력을 보거나 [디버그 로깅](https://code.claude.com/docs/ko/hooks.md#debug-hooks)으로 전체 stderr을 캡처합니다.

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

종료 코드 2로 종료하는 훅은 [실행한 작업을 차단](https://code.claude.com/docs/ko/hooks.md#exit-code-2)합니다. 플러그인의 훅이 이런 방식으로 차단하고 stderr이 차단 메시지일 때 오류는 `This hook comes from the <plugin> plugin.`으로 끝나므로 비활성화하거나 수정할 플러그인을 알 수 있습니다. v2.1.281 이전에는 오류가 플러그인의 이름을 지정하지 않았습니다.

해당 메시지가 플러그인의 경로를 공백에서 자르면 [따옴표 없는 `${CLAUDE_PLUGIN_ROOT}` 수정](#hook-error-notices-in-the-transcript)을 적용합니다.

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

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

**1. 이벤트 이름 확인**

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

**2. 매처 확인**

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

**3. 의도적으로 이벤트 트리거**

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

**4. 디버그 로그 읽기**

[디버그 로그](https://code.claude.com/docs/ko/hooks.md#debug-hooks)를 열어 어떤 훅이 일치했는지 기록합니다. 실행된 훅은 종료 코드와 함께 거기에 나타납니다.

### `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>`](#plugin-directory-not-found-at-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를 참조](https://code.claude.com/docs/ko/errors.md#plugin-command-references-user-config) 아래에 자체 항목이 있습니다.

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

플러그인은 서버를 [MCPB 번들](https://code.claude.com/docs/ko/plugins/components.md#include-a-packaged-mcpb-server)로 포함하고 `user_config`를 선언하며, 필수 설정에 저장된 값이 없거나 저장된 값이 번들 자체의 유효성 검사에 실패하므로 Claude Code는 서버 시작을 건너뜁니다. 플러그인의 나머지는 작동합니다.

`/plugin`의 **Installed** 탭에서 플러그인을 선택하고 **Configure**를 선택하여 값을 제공합니다. 저장한 후 `/plugin`은 `Configuration saved.`를 표시하고 닫으며 Claude Code는 [설치된 플러그인 관리](https://code.claude.com/docs/ko/plugins/install.md#manage-installed-plugins) 아래에 설명된 대로 플러그인을 다시 로드합니다. 해당 다시 로드가 적용되면 서버가 시작됩니다. v2.1.285 이전에는 Claude Code가 이 줄을 표시하지 않고 서버를 건너뛰었습니다.

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

`/mcp`를 실행하여 서버의 상태를 확인합니다. 서버가 정상이면 `/mcp`는 연결된 것으로 나열합니다.

서버가 시작되는 동안 인쇄한 오류를 읽으려면 `claude --debug`를 실행하고 `~/.claude/debug/<session-id>.txt`에서 로그를 엽니다. `--debug` 플래그는 터미널에 인쇄하지 않습니다.

> [!NOTE]
>
> `claude --debug`를 실행하기 전 15분 이내에 [플러그인의 stdio 서버](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers) 연결이 실패한 경우 Claude Code는 [서버를 시작하지 않습니다](https://code.claude.com/docs/ko/errors.md#skipping-connection-recent-failure-cached). 새 세션에서 `/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}`로 플러그인 내부의 경로를 작성합니다.

플러그인 디렉토리 외부에 도달하는 경로의 경우 [플러그인이 참조하는 파일이 디렉토리 외부에서 찾을 수 없음](#files-the-plugin-references-outside-its-directory-arent-found)을 참조합니다.

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

[코드 인텔리전스 플러그인](https://code.claude.com/docs/ko/plugins/code-intelligence.md)을 설치했고 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`로 로드하거나 로컬 마켓플레이스에서 설치합니다. 이러한 항목은 플러그인을 개발하는 동안 발생하는 실패를 다룹니다. 각 변경 후 확인을 실행하려면 [테스트 및 디버그](https://code.claude.com/docs/ko/plugins/create.md#test-and-debug)를 참조합니다.

플러그인의 사용자에게도 도달하는 두 가지 실패는 [플러그인이 설치되었지만 작동하지 않음](#plugin-installed-but-not-working) 아래에 항목이 있습니다:

* **발화하지 않는 훅**: [발화하지 않는 훅](#failed-to-load-hooks-from-and-hooks-that-dont-fire)을 참조합니다.
* **시작하지 않는 MCP 서버**: [시작하지 않는 MCP 서버](#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)를 참조합니다.

### `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`를 실행합니다.

> [!NOTE]
>
> v2.1.299 이전에는 이 메시지가 시작 시 `synced[0]`과 같은 태그로 레이블이 지정된 행에 나타날 수 있었습니다. 해당 행은 [claude.ai에서 동기화된](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins) 플러그인을 위한 것입니다. 이 메시지는 머신의 다른 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가 마켓플레이스 루트를 해당 디렉터리의 이름을 따서 명명한 하나의 빈 플러그인으로 로드했습니다. 플래그를 플러그인 디렉터리 자체로 가리킵니다:

```shell theme={null}
claude --plugin-dir ./my-marketplace/plugins/my-plugin
```

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

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

플러그인은 `--plugin-dir`로 소스 디렉터리에서 작동하지만 설치 후 `../shared-utils`와 같은 경로에 대한 오류로 실패합니다.

Claude Code는 설치된 플러그인을 캐시로 복사하고 거기서 로드하므로 플러그인 자체의 디렉터리 외부에 도달하는 경로는 캐시에서 아무것도 가리키지 않습니다. 공유 파일을 플러그인 디렉터리 내부로 이동하거나 내부의 심볼릭 링크를 통해 참조합니다. 캐시가 있는 위치와 경로가 확인되는 방식은 [디스크에서 플러그인 찾기](https://code.claude.com/docs/ko/plugins/loading.md#find-plugins-on-disk)를 참조합니다.

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

Windows에서 Git Bash를 통해 실행되는 플러그인 훅은 `C:\Users\you\...` 대신 `C:/Users/you/...`로 `${CLAUDE_PLUGIN_ROOT}`를 수신하고 백슬래시를 기대한 스크립트가 중단됩니다.

Git Bash가 설치되어 있으면 [셸 형식 훅](https://code.claude.com/docs/ko/hooks.md#exec-form-and-shell-form)은 기본적으로 Git Bash를 통해 실행됩니다. Git Bash를 통해 실행되는 훅의 경우 Claude Code는 Bash가 백슬래시를 이스케이프로 읽지 않도록 정방향 슬래시로 경로를 전달합니다. Bash 내장, MSYS 도구 및 기본 Windows 바이너리는 모두 해당 형식을 허용합니다.

스크립트에 백슬래시가 필요하면 [exec 형식 및 셸 형식](https://code.claude.com/docs/ko/hooks.md#exec-form-and-shell-form) 아래에 설명된 기본 경로를 유지하는 형식 중 하나로 훅을 전환합니다:

* `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`를 설정**: [첫 번째 플러그인 만들기](https://code.claude.com/docs/ko/plugins/create.md#create-your-first-plugin)의 템플릿 스킬이 설정합니다. Claude가 스스로 호출하기를 원하는 스킬에서 해당 줄을 제거합니다. [스킬을 호출할 수 있는 사람 제어](https://code.claude.com/docs/ko/skills.md#control-who-invokes-a-skill)는 필드를 다룹니다.
* **설명이 사람들이 요청하는 방식과 일치하지 않음**: [스킬이 트리거되지 않음](https://code.claude.com/docs/ko/skills.md#skill-not-triggering)의 확인을 진행합니다.
* **설명이 잘림**: 많은 스킬이 설치되면 Claude Code가 설명을 단축하여 목록의 문자 예산에 맞추고 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. [스킬 설명이 짧게 잘림](https://code.claude.com/docs/ko/skills.md#skill-descriptions-are-cut-short)을 참조합니다.

현실적인 프롬프트 전체에서 스킬이 얼마나 자주 트리거되는지 측정하려면 한 번에 하나씩 확인하는 대신 [`tool_used: Skill` 채점자](https://code.claude.com/docs/ko/plugin-evals#create-your-first-eval-suite)로 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로 플러그인 테스트](https://code.claude.com/docs/ko/plugin-evals.md)를 참조합니다.

### `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`로 값을 전달합니다. 옵션당 하나의 플래그:

```shell theme={null}
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`](https://code.claude.com/docs/ko/plugins/cli-reference#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 번들 파일](https://code.claude.com/docs/ko/plugins/components.md#include-a-packaged-mcpb-server)을 제공하는 플러그인의 경우 메시지는 `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`은 [예약된 이름](https://code.claude.com/docs/ko/plugins/manifest-reference.md#name) 중 하나입니다. | 플러그인이 수행하는 작업에 맞게 플러그인의 이름을 바꿉니다. |
| `Unknown field '<key>'` | 매니페스트에 스키마가 정의하지 않는 필드가 있습니다. | 제거하거나 메시지가 제안하는 이름을 사용합니다. Claude Code는 로드 시간에 알려지지 않은 필드를 무시합니다. `plugin.json`의 `privacyPolicyUrl` 및 기타 디렉터리 목록 필드는 [디렉터리 목록 필드](https://code.claude.com/docs/ko/plugins/manifest-reference.md#directory-listing-fields)를 참조합니다. |

각 수정 후 오류가 없을 때까지 명령을 다시 실행합니다.

`plugin.json` 필드는 [매니페스트 참조](https://code.claude.com/docs/ko/plugins/manifest-reference.md)에 있고 마켓플레이스 수준 메시지는 [마켓플레이스 유효성 검사 오류](#marketplace-validation-errors) 아래에 있습니다.

### `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`에 추가하도록 합니다. [엄격한 모드](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#strict-mode)를 참조합니다.

### `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`로 로드되지 못합니다. 두 메시지 모두 [오류 참조 항목](https://code.claude.com/docs/ko/errors.md#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory)이 있습니다.

사용자가 URL 기반 마켓플레이스를 추가하면 Claude Code는 `marketplace.json` 파일 자체만 다운로드합니다. 해당 서버에서 상대 경로로 플러그인 파일을 가져오지 않으므로 항목의 상대 경로는 절대 가져오지 않은 디렉토리를 가리킵니다. 각 항목에 Claude Code가 자체적으로 가져올 수 있는 소스(예: GitHub 저장소)를 제공합니다:

```json theme={null}
{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
```

또는 git 저장소에서 마켓플레이스를 호스팅하고 사용자에게 저장소 URL로 추가하도록 알립니다. git 소스의 경우 Claude Code가 전체 저장소를 클론하므로 상대 경로가 확인됩니다. 소스 유형은 [마켓플레이스 참조](https://code.claude.com/docs/ko/plugins/marketplace-reference.md)에 있습니다.

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

플러그인이 마켓플레이스 루트에 있으며 저장소의 git 서브모듈에 있는 파일을 실행하거나 읽습니다. 설치 후 서브모듈의 디렉토리가 비어 있습니다. v2.1.295 이전에는 Claude Code가 모든 서브모듈을 가져왔으므로 디렉토리가 채워져 있었습니다.

Claude Code가 마켓플레이스를 클론할 때는 [플러그인 파일을 포함하는 서브모듈](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository)만 가져옵니다. 루트에 있는 플러그인의 경우 플러그인 구성의 경로와 플러그인 파일의 텍스트를 읽어 판단합니다. 스크립트가 실행 중에 만들어 내는 경로는 인식할 수 없습니다.

서브모듈 내부를 가리키는 경로를 Claude Code가 읽을 수 있는 곳에 전체 형태로 작성합니다(예: 훅 명령의 `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh`). 그러면 Claude Code가 해당 플러그인에 대해 저장소의 모든 서브모듈을 가져옵니다.

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

마켓플레이스 디렉토리에서 `claude plugin validate .`를 실행했고 마켓플레이스 파일 자체에 오류 또는 경고를 보고했습니다.

`claude plugin validate`는 또한 `source`가 로컬 경로인 각 항목을 검증하고 항목의 `version`이 플러그인 자체의 매니페스트와 불일치할 때 경고합니다.

표는 마켓플레이스 수준 메시지를 나열합니다. 항목 수준 메시지는 [`claude plugin validate` 오류를 보고](#claude-plugin-validate-reports-errors) 아래의 플러그인 메시지이며 `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`로만 보고되었습니다.

## 조직에 의해 차단됨

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

### `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`가 표시되는 경우입니다.

[마켓플레이스 소스](#marketplace-source-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](https://code.claude.com/docs/ko/plugins/org.md#seed-containers-and-ci)를 참조하세요.

## 다음 단계

* [플러그인 로딩 참조](https://code.claude.com/docs/ko/plugins/loading.md): 범위, 캐시 및 우선순위가 작동하는 방식
* [플러그인 명령 참조](https://code.claude.com/docs/ko/plugins/cli-reference.md):  `claude plugin` 명령의 플래그, 기본값, 출력 및 종료 코드
* [플러그인 설치 및 관리](https://code.claude.com/docs/ko/plugins/install.md): 시작부터 설치 단계
* [조직의 플러그인 관리](https://code.claude.com/docs/ko/plugins/org.md#troubleshoot-policy): 관리자를 위한 정책 측 문제 해결