Xử lý sự cố mod

Khi module của một mod hoặc một hook của nó bị lỗi, Claude Code bỏ qua nó và session vẫn tiếp tục, nên một mod hỏng có thể trông giống hệt một mod không làm gì cả. Hãy bắt đầu bằng việc kiểm tra Claude Code đọc được gì từ mod của bạn và nó báo lỗi ở đâu, rồi tìm triệu chứng hoặc thông báo bạn đang gặp.

Tìm hiểu vì sao mod không làm gì

Khi một mod không làm gì, hãy kiểm tra Claude Code đọc được gì từ các file của mod, và dòng thông báo nó ghi khi bỏ qua thứ gì đó. Với việc đầu tiên, trong shell, chạy claude plugin validate với thư mục của mod, như claude plugin validate ./first-mod. Lệnh này phát hiện tên event viết sai, manifest hỏng, và module mà Claude Code không đọc được, mà không cần khởi động session.

Khi một module không nạp được, một hook bị bỏ qua, hoặc một mod khác từ chối mod của bạn, Claude Code ghi một dòng có tên mod của bạn. Nơi bạn đọc dòng đó tùy thuộc vào loại session:

• Session hot-reload một thư mục plugin: một dòng chữ mờ trong transcript. Đó là session tương tác bạn khởi động với --plugin-dir, hoặc session mà bạn đã bật hot reloading cho các mod do Claude viết.
• Mọi session tương tác khác, như session chạy một mod bạn cài từ marketplace: chỉ có trong debug log. Để có log, khởi động session bằng claude --debug.
• Lần chạy claude -p với --plugin-dir: stderr, ở định dạng output text mặc định. Thông báo từ chối do một mod khác chỉ có trong debug log.

Kiểm tra mods có nạp được không

Để kiểm tra cấu hình của bạn có cho phép mods nạp hay không, mà không cần cài mod nào, hãy chạy claude plugin test trong shell, từ một thư mục không chứa mod. Bạn không cần session. Thông báo nó in ra cho bạn biết trạng thái:

Thông báo có chứa	Ý nghĩa
no hooks module to load	Mods nạp được. Lệnh không tìm thấy mod nào để test trong thư mục này.
hooks modules are turned off here	Một setting đang chặn mod của bạn: disableAllHooks trong settings của bạn, hoặc policy của tổ chức
hooks modules are turned off in this process	Anthropic đã tắt các mod đã cài từ xa. Không setting nào trên máy bạn bật lại được.

Tổ chức cũng có thể đặt allowManagedModsOnly để chỉ cho phép mod của chính tổ chức, điều mà lệnh này không báo. Trong trường hợp đó, mod bạn cài không được nạp, và một thông báo cho biết lý do.

Mod không được nạp

Không có gì mà mod thêm vào xuất hiện: không có command, không có phần vẽ, và hành vi không thay đổi.

Phiên bản của bạn cũ hơn 2.1.287

claude --version in ra phiên bản cũ hơn 2.1.287. Phiên bản của bạn ra đời trước khi mods được bật mặc định.

Cập nhật Claude Code.

Dòng mods active không có tên mod

Không có gì mà mod thêm vào xuất hiện, và dòng mods active trong /plugin không có tên nó. Hooks module chưa được nạp. Khi Claude Code từ chối nó, debug log có một dòng bắt đầu bằng hooks module, tên mod và not loaded:, ví dụ hooks module first-mod@inline not loaded: disableAllHooks in managed settings với một mod nạp bằng --plugin-dir.

Đọc lý do sau dấu hai chấm. Phần Thông báo từ chối liệt kê từng lý do. Nếu log không có dòng như vậy, hãy lần lượt xem các mục khác trong nhóm này.

Một số setting dừng mod nhưng để phần còn lại của plugin hoạt động. Phần Bật hoặc tắt mods nêu tên các setting đó.

Lần chạy claude -p in ra hooks module not loaded

Dòng bắt đầu bằng tên mod và được ghi ra stderr. Hooks module đã bị từ chối. Lần chạy non-interactive không có transcript, nên thông báo được ghi ra stderr.

Đọc lý do sau dấu hai chấm. Phần Thông báo từ chối liệt kê từng lý do.

Thông báo từ chối

Mỗi thông báo dưới đây đứng sau hooks module, tên mod và not loaded: trong debug log.

Thông báo bắt đầu bằng	Ý nghĩa
hooks modules are turned off for installed plugins in this process	Anthropic đã tắt các mod đã cài từ xa. Không setting nào trên máy bạn bật lại được.
disableAllHooks in managed settings	Tổ chức của bạn đã tắt hook từ các plugin đã cài
only managed plugins and built-in plugins run	allowManagedHooksOnly đã được đặt, hoặc disableAllHooks được đặt trong một settings file không phải managed settings
installed plugins that are not managed load no hooks module in this mode (--bare)	Bạn khởi động Claude Code với --bare
another plugin of that name loads first	Hai plugin trùng tên. Plugin được quản lý (managed), hoặc plugin được nạp trước, sẽ được dùng.

Thông báo từ guard tích hợp sẵn

Trên máy có managed settings, hoặc với user đăng nhập bằng gói Team hay Enterprise, guard tích hợp sẵn có thể từ chối một mod hoặc một câu trả lời của nó. Mỗi thông báo nêu tên option mà administrator của tổ chức đặt để thay đổi quy tắc.

Thông báo có chứa	Ý nghĩa	Xuất hiện ở đâu
mods are limited to your organization's by policy (allowManagedModsOnly)	Tổ chức của bạn chỉ cho phép mod của chính tổ chức, nên mod của bạn không được nạp	Debug log, và transcript trong một session hot-reload thư mục plugin
tried to lift a deny rule in your settings	Hook tool.check của mod đã duyệt một call mà rule deny từ chối. Call vẫn bị từ chối.	Transcript và debug log, mỗi mod một lần trong một session. Trong lần chạy claude -p, chỉ có trong debug log.
the deny rules in your settings could not be checked for this call, so it is refused	Guard bị lỗi khi kiểm tra một call mà mod đã duyệt, nên nó từ chối call đó	Là lý do Claude đọc được cho call bị từ chối

validate pass nhưng không có dòng hooks

hooks/hooks.json không có key modules, hoặc key bị viết sai.

Thêm "modules": ["./register.js"].

hooks module did not load

Dòng bắt đầu bằng tên mod, rồi hooks module did not load: và một lý do, lý do này chỉ ra file và dòng khi lỗi nằm trong code của bạn. Claude Code không nạp được module, ví dụ vì code ở top level đã ném lỗi.

Sửa lỗi mà lý do nêu ra.

options do not fit plugin.json userConfig

Dòng bắt đầu bằng tên mod, rồi hooks module did not load: options do not fit plugin.json userConfig: và một lý do. Một option không vượt qua validate với field userConfig của nó, như một số lớn hơn max của field, hoặc một field bắt buộc không có giá trị.

Đặt hoặc sửa giá trị. Cuối dòng ghi tên mục pluginConfigs tương ứng trong settings.json.

Không mod nào được nạp trong thư mục bạn mở lần đầu

Bạn chưa trả lời trust prompt cho thư mục đó.

Khởi động một session tương tác trong thư mục đó bằng claude, và chấp nhận trust prompt hiện ra lúc mở.

Không plugin đã cài nào được nạp

Bạn đã khởi động Claude Code với --safe-mode.

Khởi động lại mà không có cờ đó.

Hook bị bỏ qua hoặc mod bị gỡ

Mod đã được nạp, rồi sau đó Claude Code bỏ qua một hook của nó hoặc gỡ (unload) nó.

hook skipped

Dòng ghi tên mod và event, rồi hook skipped: và một lý do, như first-mod: tool.call hook skipped: threw Error: boom. Một hook đã ném lỗi, vượt giới hạn thời gian, hoặc trả về kết quả sai dạng. Dòng này xuất hiện một lần cho mỗi event và mỗi loại lỗi, cho đến khi mod reload.

Sửa lỗi. Debug log có một dòng cho mọi lần xảy ra.

no command.run hook answered it

Bạn chạy một command mà mod đã thêm, và câu trả lời nêu tên mod và command, như first-mod registered /tally but no command.run hook answered it, rồi bảo bạn thêm một hook. Claude Code in câu trả lời này khi command đi tới cuối chuỗi mà không ai trả lời, điều xảy ra trong hai trường hợp:

• Không hook nào trả lời command: module không có hook command.run, bộ lọc của hook ghi tên một command khác, hoặc hook trả về next(e)
• Claude Code đã bỏ qua hook: mục hook skipped liệt kê các lý do. Truyền focus: false cho $.ui.open là một cách dẫn tới trường hợp này.

Nếu module đã có hook mà câu trả lời mô tả, hãy tìm một dòng hook skipped có tên command.run, dòng đó cho biết lý do. Một test chạy command này sẽ fail với cùng lý do.

it crashed the hooks worker

Dòng bắt đầu bằng tên mod, như first-mod was unloaded: it crashed the hooks worker. Các mod đã cài dùng chung một worker thread. Worker đã ngừng phản hồi hoặc bị crash, và Claude Code truy ra nguyên nhân là mod này nên đã gỡ nó. Một hook chặn thread, như một vòng lặp không bao giờ await, là một nguyên nhân.

Sửa hook.

mods that run in the hooks worker are off for this session

Dòng có nội dung hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Worker đã dừng ba lần và Claude Code không truy được nguyên nhân về một mod cụ thể, nên nó gỡ mọi mod không phải tích hợp sẵn, kể cả mod do tổ chức của bạn cài. Dòng này xuất hiện trong transcript ở mọi session tương tác.

Chạy /reload-plugins để nạp lại chúng.

Tool call bị từ chối

Mod đã được nạp và hook của nó chạy, nhưng một tool call mà nó đụng tới bị từ chối.

a hook changed this call's input after the model wrote it

Ở auto mode, một tool call bị từ chối đưa ra lý do này. Một hook đã thay đổi input của tool call sau khi server-side classifier xem xét nó, nên lần xem xét đó không bao quát thứ sẽ chạy. Hook đó có thể là hook tool.call hoặc turn.step của một mod, hoặc một settings hook PreToolUse. Thông báo không nói là hook nào.

Thông báo bảo Claude thực hiện lại call một lần nữa đúng như đã ghi. Nếu lần đó cũng bị từ chối, nghĩa là hook thay đổi input mọi lần, nên hãy tắt mod hoặc hook đó, hoặc rời auto mode và tự duyệt call.

Thông báo về các deny rule trong settings của bạn

tried to lift a deny rule in your settings và the deny rules in your settings could not be checked for this call, so it is refused đều đến từ guard tích hợp sẵn.

Tra cứu chúng trong phần Thông báo từ guard tích hợp sẵn.

Phần vẽ không xuất hiện hoặc không phản hồi

Mod đã được nạp, nhưng pane, band hoặc các control của nó không hoạt động như bạn mong đợi.

Pane hoặc band trống, hoặc hiển thị nội dung thường lệ của Claude Code

Cây mà hook của bạn trả về không hợp lệ. Với --plugin-dir, transcript ghi ui.render (Pane) refused: kèm lý do, như first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Debug log có a hook returned a tree that does not validate với cùng lý do.

Đọc lý do trên dòng đó. Nguyên nhân thường gặp là một prop mà element không nhận và một element mà ứng dụng không có.

$.ui.open chạy nhưng không có pane nào xuất hiện

Lời gọi không xuất phát từ hành động của user, và terminal hẹp hơn độ rộng mà pane đó cần.

Mở pane từ một command hoặc một nút bấm, hoặc kiểm tra kết quả isPlaced của lời gọi. Xem Mở pane đúng lúc.

Hotkey không có tác dụng

Pane của bạn không có keyboard focus.

Nhấn Ctrl+X rồi Tab, hoặc click vào pane. Mở pane với focus: true từ một command.

Phần vẽ hoạt động trong terminal nhưng không hoạt động trong ứng dụng Desktop

Site hoặc element không khả dụng ở đó.

Kiểm tra bảng render site và element.

Mất chỉnh sửa hoặc mất giá trị

Mod vẫn chạy, nhưng một thay đổi bạn đã làm hoặc một giá trị nó đã giữ không còn nữa.

Chỉnh sửa của bạn không có hiệu lực

Bạn đang sửa một plugin đã cài. Claude Code chạy bản đã cache của phiên bản đã cài.

Phát triển với --plugin-dir trỏ tới bản làm việc của bạn, như claude --plugin-dir ./first-mod, cách này tự reload khi bạn lưu.

Một giá trị bị reset khi module reload

Các biến cấp module được khởi tạo lại mỗi lần reload.

Giữ giá trị trong $.state hoặc $.store.

Một giá trị bị reset sau /clear, /resume hoặc /branch

Một giá trị bị reset, hoặc một giá trị đã lưu bị thay bằng giá trị mặc định. Mỗi command đó đặt $.state về mặc định, và session.start không chạy lại.

Nạp lại giá trị đã lưu trong một hook classic.SessionStart.

Đọc debug log

Debug log có một dòng cho mọi module mà Claude Code nạp hoặc từ chối, mọi hook bị lỗi, và mọi kết quả bị từ chối, nên đây là nơi cần xem khi transcript không hiện gì. Để ghi log, trong shell, khởi động Claude Code với --debug, hoặc với --debug-file <path> để chọn nơi ghi:

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

Trong một terminal khác, theo dõi file và lọc theo tên mod của bạn:

tail -f ./mod-debug.log | grep first-mod

Một mod đã được nạp có một dòng ghi tên nó và liệt kê các event nó xử lý. Mod nạp bằng --plugin-dir xuất hiện dưới tên của nó cộng thêm @inline:

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

Một phần vẽ không hợp lệ được tính là một kết quả bị từ chối và cũng có một dòng. Để tự ghi dòng của bạn vào log, gọi $.ui.log với tham số thứ hai, như $.ui.log('message', { to: 'debug' }). Không có tham số thứ hai, $.ui.log thêm một dòng chữ mờ vào transcript.

Trong lúc bạn sửa một mod nạp bằng --plugin-dir, transcript hiển thị một dòng cho mỗi lần reload, ghi tên mod và liệt kê các hook của nó. Nếu một lần lưu làm hỏng module, dòng đó ghi reload failed, the previous version stays loaded: kèm lý do, và phiên bản chạy được gần nhất vẫn tiếp tục chạy.

Đọc tiếp

• Kiểm thử mod: bắt lỗi trước khi chúng xuất hiện trong session
• Troubleshoot plugins: các vấn đề khi cài và nạp plugin không riêng gì mod

Nguồn

Biên soạn theo Troubleshoot a mod trong tài liệu chính thức của Claude Code.

Bài tiếp theo: Tham chiếu Mods - Tra cứu đầy đủ cấu trúc file, event, phương thức mods API, render site, element, giới hạn và settings.