mod이 아무것도 하지 않는 이유 파악
mod이 아무것도 하지 않을 때, 두 가지 확인으로 이유를 찾을 수 있습니다: Claude Code가 mod의 파일에서 읽은 내용과 무언가를 건너뛸 때 작성하는 줄입니다. 첫 번째의 경우, 셸에서claude plugin validate를 mod의 디렉터리와 함께 실행합니다(예: claude plugin validate ./first-mod). 이는 세션을 시작하지 않고도 잘못된 이벤트, 잘못된 manifest, Claude Code가 읽을 수 없는 모듈을 포착합니다.
모듈이 로드되지 않거나, hook이 건너뛰어지거나, 다른 mod이 귀사의 mod을 거부할 때, Claude Code는 귀사의 mod의 이름을 지정하는 한 줄을 작성합니다. 해당 줄을 읽는 위치는 세션에 따라 다릅니다:
- 플러그인 디렉터리를 핫 리로드하는 세션: 트랜스크립트의 흐린 줄입니다. 이는
--plugin-dir로 시작한 대화형 세션이거나, Claude가 작성한 mod에 대해 핫 리로딩을 활성화한 세션입니다. - 마켓플레이스에서 설치한 mod을 실행하는 것과 같은 다른 모든 대화형 세션: 디버그 로그만 해당합니다. 하나를 얻으려면
claude --debug로 세션을 시작합니다. --plugin-dir을 사용한claude -p실행: stderr, 기본 텍스트 출력 형식입니다. 다른 mod의 거부는 디버그 로그로만 이동합니다.
mod이 로드될 수 있는지 확인
설정이 mod을 로드할 수 있는지 확인하려면 mod을 설치하지 않고도 셸에서claude plugin test를 실행합니다(mod을 보유하지 않은 디렉터리에서). 세션이 필요하지 않습니다. 인쇄되는 메시지는 상태를 알려줍니다:
조직은 또한
allowManagedModsOnly를 설정하여 자신의 mod만 허용할 수 있으며, 이 명령은 이를 보고하지 않습니다. 이 경우 설치한 mod이 로드되지 않으며, 메시지가 이유를 설명합니다.
mod이 로드되지 않음
mod이 추가하는 것이 아무것도 나타나지 않습니다: 명령, 그리기, 동작 변화가 없습니다.버전이 2.1.287보다 오래됨
claude --version은 2.1.287보다 오래된 버전을 인쇄합니다. 버전이 mod이 기본적으로 켜지기 전의 것입니다.
Claude Code 업데이트.
mods active 줄이 mod의 이름을 지정하지 않음
mod이 추가하는 것이 아무것도 나타나지 않으며, /plugin의 mods active 줄이 이를 이름 지정하지 않습니다. hooks 모듈이 로드되지 않았습니다. Claude Code가 이를 거부했을 때, 디버그 로그에는 hooks module, mod의 이름, not loaded:로 시작하는 줄이 있습니다(예: --plugin-dir로 로드된 mod의 경우 hooks module first-mod@inline not loaded: disableAllHooks in managed settings).
콜론 뒤의 이유를 읽습니다. 거부 메시지 섹션에는 각각이 나열되어 있습니다. 로그에 그러한 줄이 없으면 이 그룹의 다른 항목을 통해 작업합니다.
claude -p 실행이 hooks module not loaded 인쇄
줄은 mod의 이름으로 시작하여 stderr로 이동합니다. hooks 모듈이 거부되었습니다. 비대화형 실행에는 트랜스크립트가 없으므로 메시지는 stderr로 이동합니다.
콜론 뒤의 이유를 읽습니다. 거부 메시지 섹션에는 각각이 나열되어 있습니다.
거부 메시지
각각은 디버그 로그에서hooks module, mod의 이름, not loaded: 뒤에 옵니다.
기본 제공 가드의 메시지
관리되는 설정이 있는 컴퓨터 또는 Team 또는 Enterprise 플랜으로 로그인한 사용자의 경우, 기본 제공 가드는 mod 또는 해당 답변 중 하나를 거부할 수 있습니다. 각 메시지는 조직의 관리자가 규칙을 변경하도록 설정하는 옵션의 이름을 지정합니다.validate가 통과하고 hooks 줄을 나열하지 않음
hooks/hooks.json에 modules 키가 없거나 키가 잘못 입력되었습니다.
"modules": ["./register.js"]를 추가합니다.
hooks module did not load
줄은 mod의 이름으로 시작한 다음 hooks module did not load: 및 이유가 뒤따르며, 문제가 코드에 있을 때 파일과 줄을 제공합니다. Claude Code가 모듈을 로드할 수 없었습니다(예: 최상위 코드가 throw되었기 때문).
이유가 이름 지정하는 오류를 수정합니다.
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 항목의 이름을 지정합니다.
처음 열린 디렉터리에서 mod이 로드되지 않음
디렉터리에 대한 신뢰 프롬프트에 답변하지 않았습니다.claude를 사용하여 해당 디렉터리에서 대화형 세션을 시작하고 열리는 신뢰 프롬프트를 수락합니다.
설치된 플러그인이 로드되지 않음
--safe-mode로 Claude Code를 시작했습니다.
플래그 없이 시작합니다.
hook이 건너뛰어지거나 mod이 언로드됨
mod이 로드되었고, Claude Code가 해당 hook 중 하나를 건너뛰거나 언로드했습니다.hook skipped
줄은 mod과 이벤트의 이름을 지정한 다음 hook skipped: 및 이유를 말합니다(예: first-mod: tool.call hook skipped: threw Error: boom). hook이 throw되었거나, 10초 시간 제한을 초과하여 실행되었거나, 잘못된 모양의 결과를 반환했습니다. 줄은 mod이 다시 로드될 때까지 각 이벤트 및 실패 종류마다 한 번씩 나타납니다.
오류를 수정합니다. 디버그 로그에는 모든 발생에 대한 줄이 있습니다.
it crashed the hooks worker
줄은 mod의 이름으로 시작합니다(예: first-mod was unloaded: it crashed the hooks worker). 설치된 mod은 하나의 워커 스레드를 공유합니다. 워커가 응답을 중지하거나 충돌했으며, Claude Code가 이를 이 mod으로 추적하고 언로드했습니다. 스레드를 차단하는 hook(예: 절대 await하지 않는 루프)이 한 가지 원인입니다.
hook을 수정합니다.
mods that run in the hooks worker are off for this session
줄은 hooks: mods that run in the hooks worker are off for this session: it crashed 3 times를 읽습니다. 워커가 3번 중지되었고 Claude Code가 중지를 하나의 mod으로 추적할 수 없어서 기본 제공되지 않은 모든 mod(조직이 설치하는 mod 포함)을 언로드했습니다. 이 줄은 모든 대화형 세션의 트랜스크립트에 도달합니다.
/reload-plugins를 실행하여 다시 로드합니다.
도구 호출이 거부됨
mod이 로드되었고 해당 hook이 실행되며, 이를 건드린 도구 호출이 거부됩니다.a hook changed this call's input after the model wrote it
자동 모드에서 거부된 도구 호출은 이 이유를 제공합니다. hook이 서버 측 분류자가 검토한 후 도구 호출의 입력을 변경했으므로 해당 검토는 실행될 내용을 포함하지 않습니다. hook은 mod의 tool.call 또는 turn.step hook이거나 PreToolUse 설정 hook일 수 있습니다. 메시지는 어느 것인지 말하지 않습니다.
메시지는 Claude에게 기록된 대로 호출을 다시 한 번 발급하도록 지시합니다. 그것도 거부되면 hook은 매번 입력을 변경하므로 mod 또는 hook을 끄거나 자동 모드를 떠나 호출을 직접 승인합니다.
설정의 거부 규칙에 대한 메시지
tried to lift a deny rule in your settings 및 the deny rules in your settings could not be checked for this call, so it is refused는 모두 기본 제공 가드에서 옵니다.
기본 제공 가드의 메시지에서 조회합니다.
그리기가 나타나지 않거나 응답하지 않음
mod이 로드되었고 해당 pane, band 또는 컨트롤이 예상대로 작동하지 않습니다.pane 또는 band가 비어 있거나 Claude Code의 일반적인 콘텐츠를 표시함
hook이 반환한 tree가 유효성 검사를 통과하지 못했습니다.--plugin-dir을 사용하면 트랜스크립트는 ui.render (Pane) refused:를 이유와 함께 말합니다(예: first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own). 디버그 로그에는 a hook returned a tree that does not validate가 동일한 이유와 함께 있습니다.
해당 줄의 이유를 읽습니다. 일반적인 원인은 요소가 취하지 않는 prop과 앱이 없는 요소입니다.
$.ui.open이 실행되고 pane이 나타나지 않음
호출이 사용자가 한 것에서 오지 않았으며 터미널이 144열보다 좁습니다.
명령 또는 버튼에서 pane을 열거나 호출의 isPlaced 결과를 확인합니다. 올바른 시간에 pane 열기를 참조합니다.
핫키가 아무것도 하지 않음
pane에 키보드 포커스가 없습니다. Ctrl+X를 누른 다음 Tab을 누르거나 pane을 클릭합니다.focus: true로 명령에서 열기합니다.
그리기가 터미널에서 작동하고 Desktop 앱에서는 작동하지 않음
사이트 또는 요소를 사용할 수 없습니다. 렌더 사이트 및 요소 테이블을 확인합니다.편집 또는 값이 손실됨
mod이 실행되고 변경하거나 유지한 값이 없습니다.편집이 적용되지 않음
설치한 플러그인을 편집하고 있습니다. Claude Code는 설치된 버전의 캐시된 복사본을 실행합니다.claude --plugin-dir ./first-mod와 같이 작업 복사본을 가리키는 --plugin-dir로 개발합니다. 이는 저장할 때 다시 로드됩니다.
모듈이 다시 로드될 때 값이 재설정됨
모듈 수준 변수는 각 다시 로드 시 다시 초기화됩니다. 값을$.state 또는 $.store에 유지합니다.
/clear, /resume 또는 /branch 후 값이 재설정됨
값이 재설정되거나 저장된 값이 기본값으로 대체됩니다. 이러한 각 명령은 $.state를 기본값으로 재설정하며, session.start는 다시 실행되지 않습니다.
classic.SessionStart hook에서 저장된 값을 다시 로드합니다.
디버그 로그 읽기
디버그 로그에는 Claude Code가 로드하거나 거부하는 모든 모듈, 실패하는 모든 hook, 거부하는 모든 결과에 대한 줄이 있으므로 트랜스크립트가 아무것도 표시하지 않을 때 볼 위치입니다. 하나를 작성하려면 셸에서--debug로 Claude Code를 시작하거나 --debug-file <path>로 위치를 선택합니다:
--plugin-dir로 로드된 mod은 이름 뒤에 @inline으로 나타납니다:
$.ui.log를 두 번째 인수와 함께 호출합니다(예: $.ui.log('message', { to: 'debug' })). 두 번째 인수 없이 $.ui.log는 트랜스크립트에 흐린 줄을 추가합니다.
--plugin-dir로 로드된 mod을 편집하는 동안 트랜스크립트는 mod의 이름을 지정하고 해당 hook을 나열하는 각 다시 로드에 대한 줄을 표시합니다. 저장이 모듈을 손상시키면 줄은 reload failed, the previous version stays loaded:를 이유와 함께 말하며, 마지막 작동 버전이 계속 실행됩니다.
다음 단계
- mod 테스트: 문제가 세션에 도달하기 전에 포착합니다
- 플러그인 문제 해결: mod에 특정하지 않은 플러그인 설치 및 로드 문제