diff --git a/doc/api/module.md b/doc/api/module.md index 83f4b6e32f8d0d..5013580e78cdd6 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -111,6 +111,17 @@ changes: Register a module that exports [hooks][] that customize Node.js module resolution and loading behavior. See [Customization hooks][]. +> **Warning** When setting up a `MessageChannel` to communicate with hooks, +> beware that this can lead to a deadlock. For example, you have 2 modules, +> A and B. "A" is registered first and sets up a message channel, which it uses +> in its `resolve` hook. After "A" is registered, "B" is registered. Resolving +> "B"'s specifier will go through "A"'s `resolve` hook, which will try to +> communicate with a locked thread that is busy trying to register "B"'s hooks. +> Since registering "B" depends on resolving "B"'s specifier, and resolving +> "B"'s specifier is blocked by "A"'s communication request that is itself +> blocked by the pending registration that started the chain, the application +> becomes deadlocked. + ### `module.syncBuiltinESMExports()`