From 05c5619f39766cdf2e3f6ed8b938f641ee1f6388 Mon Sep 17 00:00:00 2001 From: Paul Bouchon Date: Thu, 20 Aug 2026 15:49:53 -0400 Subject: [PATCH] doc: warn against awaiting replies in module hooks Awaiting a reply from the registering thread inside a resolve or load hook deadlocks: resolution is synchronous from that thread's perspective, so it is blocked in the request and cannot answer. Fixes: https://github.com/nodejs/node/issues/63085 Signed-off-by: Paul Bouchon --- doc/api/module.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/api/module.md b/doc/api/module.md index 1aac20780c4d..bd30f4f5c3ca 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -1278,6 +1278,13 @@ register('./my-hooks.mjs', { }); ``` +A hook can send messages to the thread that registered it at any time, as +above. It must not block on a reply from that thread: resolution and loading +are synchronous from the perspective of the thread that triggered them, so that +thread is blocked until the hook settles and cannot answer in the meantime. +Hooks can otherwise be fully asynchronous; it is only a reply over this +message channel that cannot be awaited. + #### Asynchronous hooks accepted by `module.register()`