mod가 아무 동작도 하지 않는 이유 찾기
mod가 아무 동작도 하지 않으면 Claude Code가 mod의 파일에서 무엇을 읽는지, 그리고 무언가를 건너뛸 때 기록하는 줄을 확인합니다. 첫 번째의 경우, 셸에서claude plugin validate ./first-mod처럼 mod의 디렉터리를 지정하여 claude plugin validate를 실행합니다. 이 명령은 세션을 시작하지 않고도 철자가 틀린 이벤트, 잘못된 매니페스트, Claude Code가 읽을 수 없는 모듈을 찾아냅니다.
모듈이 로드되지 않거나, 훅을 건너뛰거나, 다른 mod가 사용자의 mod를 거부하면 Claude Code는 해당 mod의 이름이 포함된 한 줄을 기록합니다. 이 줄을 확인하는 위치는 세션에 따라 다릅니다.
- 플러그인 디렉터리를 핫 리로드하는 세션: 트랜스크립트에 흐리게 표시되는 줄입니다.
--plugin-dir로 시작한 대화형 세션이나, Claude가 작성한 mod에 대해 핫 리로드를 활성화한 세션이 이에 해당합니다. - 그 외의 대화형 세션(예: 마켓플레이스에서 설치한 mod를 실행하는 세션): 디버그 로그에만 기록됩니다. 디버그 로그를 얻으려면
claude --debug로 세션을 시작합니다. --plugin-dir을 사용한claude -p실행: 기본 텍스트 출력 형식에서 stderr로 출력됩니다. 다른 mod에 의한 거부는 디버그 로그에만 기록됩니다.
mod를 로드할 수 있는지 확인하기
mod를 설치하지 않고도 현재 설정에서 mod를 로드할 수 있는지 확인하려면, mod가 없는 디렉터리에서 셸에claude plugin test를 실행합니다. 세션은 필요하지 않습니다. 출력되는 메시지를 통해 상태를 알 수 있습니다.
조직은
allowManagedModsOnly를 설정하여 조직 자체의 mod만 허용할 수도 있으며, 이 명령은 이를 보고하지 않습니다. 이 경우 Claude Code는 사용자가 설치한 mod를 거부하며, 그 이유를 알려 주는 메시지가 표시됩니다.
mod가 로드되지 않음
mod가 추가하는 항목이 전혀 나타나지 않습니다. 명령도, 그리기도, 동작의 변화도 없습니다.버전이 너무 오래됨
사용해야 하는 버전과 현재 버전을 확인하는 방법을 참조하세요.mods active 줄에 mod 이름이 없음
mod가 추가하는 항목이 전혀 나타나지 않고, /plugin의 mods active 줄에도 mod 이름이 표시되지 않습니다. 훅 모듈이 로드되지 않은 것입니다. Claude Code가 훅 모듈을 거부한 경우, 디버그 로그에 hooks module, mod 이름, not loaded:로 시작하는 줄이 있습니다. 예를 들어 --plugin-dir로 로드한 mod의 경우 hooks module first-mod@inline not loaded: disableAllHooks in managed settings와 같이 표시됩니다.
콜론 뒤의 이유를 확인합니다. 거부 메시지 섹션에 각 메시지가 나와 있습니다. 로그에 이러한 줄이 없다면 이 그룹의 다른 항목을 차례로 확인합니다.
일부 설정은 mod를 중지시키지만 해당 플러그인의 나머지 부분은 계속 작동하게 둡니다. mod 켜기 또는 끄기에 해당 설정이 나와 있습니다.
claude -p 실행 시 hooks module not loaded가 출력됨
이 줄은 mod 이름으로 시작하며 stderr로 출력됩니다. 훅 모듈이 거부된 것입니다. 비대화형 실행에는 트랜스크립트가 없으므로 메시지가 stderr로 출력됩니다.
콜론 뒤의 이유를 확인합니다. 거부 메시지 섹션에 각 메시지가 나와 있습니다.
거부 메시지
디버그 로그에서 다음 각 메시지는hooks module, mod 이름, not loaded: 뒤에 나옵니다.
기본 제공 가드의 메시지
관리형 설정이 있는 컴퓨터에서, 또는 Team이나 Enterprise 플랜으로 로그인한 사용자의 경우, 기본 제공 가드가 mod 또는 mod의 응답 중 하나를 거부할 수 있습니다. 각 메시지에는 조직의 관리자가 규칙을 변경하기 위해 설정하는 옵션이 명시되어 있습니다.validate는 통과하지만 hooks 줄이 나열되지 않음
hooks/hooks.json에 modules 키가 없거나 키의 철자가 잘못되었습니다.
"modules": ["./register.js"]를 추가합니다.
hooks module did not load
이 줄은 mod 이름으로 시작하고, 그 뒤에 hooks module did not load:와 이유가 나옵니다. 문제가 코드에 있는 경우 이유에 파일과 줄이 표시됩니다. Claude Code가 모듈을 로드할 수 없었습니다. 예를 들어 모듈의 최상위 코드에서 예외가 발생한 경우입니다.
이유에 명시된 오류를 수정합니다.
options do not fit plugin.json userConfig
이 줄은 mod 이름으로 시작하고, 그 뒤에 hooks module did not load: options do not fit plugin.json userConfig:와 이유가 나옵니다. 옵션이 해당 userConfig 필드에 대한 검증에 실패했습니다. 예를 들어 숫자가 필드의 max를 초과하거나, 필수 필드에 값이 없는 경우입니다.
값을 설정하거나 변경합니다. 줄 끝에 settings.json의 해당 pluginConfigs 항목이 명시되어 있습니다.
code nested too deep to scan: more than 2000 scopes
이 줄은 mod 이름으로 시작하고, 그 뒤에 hooks module did not load:, 파일, code nested too deep to scan: more than 2000 scopes가 나옵니다. 훅 모듈의 파일은 함수, 블록, 루프와 같은 범위를 2,000단계보다 깊게 중첩할 수 없습니다. claude plugin validate도 같은 이유를 보고합니다.
범위가 덜 깊게 중첩되도록 코드를 다시 작성합니다.
처음 연 디렉터리에서 mod가 로드되지 않음
해당 디렉터리의 신뢰 프롬프트에 응답하지 않았습니다. 해당 디렉터리에서claude로 대화형 세션을 시작하고, 세션 시작 시 표시되는 신뢰 프롬프트를 수락합니다.
설치된 플러그인이 전혀 로드되지 않음
Claude Code를--safe-mode로 시작했습니다.
이 플래그 없이 시작합니다.
Claude Code가 핫 리로드 활성화 여부를 더 이상 묻지 않음
Claude가 대화형 세션에서 mod를 작성했지만 아무것도 로드되지 않고, Claude Code가 핫 리로드를 활성화할지 다시 묻지 않습니다. 답을 선택하지 않은 채 질문이 세 번 종료되면 핫 리로드는 꺼진 상태로 유지됩니다. 예를 들어askUserQuestionTimeout을 설정했는데 응답하기 전에 시간이 지나면 질문이 그렇게 종료됩니다. Claude Code는 AskUserQuestion이 사용하는 것과 동일한 질문 대화 상자에서 묻기 때문에 이 설정이 여기에도 적용됩니다. 사용자가 직접 닫은 질문은 세 번에 포함되지 않습니다.
mod를 실행하려면 mod 디렉터리를 mods 폴더 밖으로 복사한 다음, 셸에서 claude --plugin-dir ~/mods/git-branch와 같이 --plugin-dir로 새 세션을 시작합니다.
훅이 건너뛰어지거나 mod가 언로드되는 경우
mod가 로드된 후 Claude Code가 해당 mod의 훅 중 하나를 건너뛰었거나 mod를 언로드했습니다.hook skipped
이 줄은 mod와 이벤트의 이름을 표시한 다음 hook skipped:와 이유를 표시합니다. 예를 들면 first-mod: tool.call hook skipped: threw Error: boom과 같습니다. 훅이 예외를 발생시켰거나, 시간 제한을 초과했거나, 잘못된 형태의 결과를 반환한 경우입니다. 이 줄은 mod가 다시 로드될 때까지 이벤트와 실패 유형마다 한 번씩 표시됩니다.
오류를 수정하십시오. 디버그 로그에는 발생할 때마다 한 줄씩 기록됩니다.
no command.run hook answered it
mod가 추가한 명령을 실행하면, 응답에 mod와 명령의 이름이 표시되고(예: first-mod registered /tally but no command.run hook answered it) 훅을 추가하라는 안내가 이어집니다. Claude Code는 명령이 응답 없이 체인의 끝에 도달하면 이 응답을 출력하며, 이는 다음 두 가지 경우에 발생합니다.
- 명령에 응답한 훅이 없는 경우: 모듈에
command.run훅이 없거나, 훅의 필터가 다른 명령을 지정하거나, 훅이next(e)를 반환한 경우입니다 - Claude Code가 훅을 건너뛴 경우: