Skip to content

src,node-api: keep initializer errors of linked bindings and addons - #67571

Open
r-Larch wants to merge 4 commits into
nodejs:mainfrom
r-Larch:src-linked-binding-rethrow
Open

r-Larch wants to merge 4 commits into
nodejs:mainfrom
r-Larch:src-linked-binding-rethrow

Conversation

@r-Larch

@r-Larch r-Larch commented Nov 18, 2026 •

Copy link
Copy Markdown

After talking to @vmoroz and following his suggestion in microsoft/node-api-dotnet#512 (comment)
I've changed the PR to adopt his changes in microsoft/v8-jsi#289


When the initializer of a linked binding or a Node-API addon throws, the error
can get lost and the call returns the module's exports instead:

  • process._linkedBinding() of a linked binding whose register function throws
    returns the empty exports object.
  • require() of a Node-API addon whose init function throws and returns a new
    exports object returns that object.

In both cases Node.js makes a V8 API call after the initializer returns:
GetLinkedBinding() reads module.exports, and napi_module_register_by_symbol()
sets it. Such calls clear a pending exception (they enter through
PrepareForExecutionScope), so the error never reaches the caller. Plain C++ and
Node-API linked bindings are both affected. Addons loaded with process.dlopen()
are only affected through the Node-API path, because DLOpen() itself makes no V8
call after the register function.

The fix returns right after the initializer when it left an exception pending
(isolate->HasPendingException(), as already used in src/node_sqlite.cc), in
both places, before module.exports is touched.

The approach follows @vmoroz's fix in LibNode (microsoft/v8-jsi#289), who
suggested bringing it upstream in this PR:
microsoft/node-api-dotnet#512 (comment).
An earlier revision of this PR used a TryCatch and ReThrow() in
GetLinkedBinding() only; the pending-exception check is simpler and also covers
the Node-API path.

I found this while embedding Node.js 26 from .NET
(microsoft/node-api-dotnet#512): with LibNode 20 (Node.js 20.18) the error of a
linked Node-API module's initializer reached process._linkedBinding(), with
LibNode 26 it no longer did. LibNode 26.1.2 ships the fix above, and
node-api-dotnet's test asserts the error again with it.

Tests

  • test/cctest/test_linked_binding.cc: four linked bindings whose initializer
    throws (plain C++, plain C++ that sets module.exports first, Node-API,
    Node-API that returns new exports); each expects init failed from
    process._linkedBinding().
  • test/node-api/test_init_exception: an addon whose init throws and returns new
    exports; require() must throw Error during Init.

With main's src/ files, all four cctests and the addon test fail; with the
change, all 15 LinkedBindingTest.* tests and the addon test pass. cpplint and
eslint are clean. I ran these on Linux (x64, GCC 13.3), not the full test suite.

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. labels Nov 18, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Welcome to Node.js, and thank you for your first contribution!

Before review, please take a moment to read:

Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal.

r-Larch added a commit to r-Larch/node-api-dotnet that referenced this pull request Nov 18, 2026
With LibNode 26 the error thrown by a linked module's init function no
longer reaches the caller of process._linkedBinding(): Node.js
GetLinkedBinding() reads module.exports after the init function returns,
and that V8 API call clears the pending exception. This affects every
linked binding and is fixed in nodejs/node#67571.

The test now checks that the error does not stay pending on the
runtime's env, which fails without moving it to the module's env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GetLinkedBinding() reads module.exports after it calls the register
function of a linked binding. If the register function threw, that V8
API call clears the pending exception (PrepareForExecutionScope), so
the error never reaches the caller of process._linkedBinding(), which
gets the empty exports object instead. This affects every linked
binding, including Node-API ones, whose module registration already
rethrows the error of the initializer.

Addons loaded with process.dlopen() are not affected, because DLOpen()
does not call into V8 after the register function. Rethrow the error
before reading module.exports.

Signed-off-by: René Larch <renelarch@gmail.com>
@r-Larch
r-Larch force-pushed the src-linked-binding-rethrow branch from 936418e to e354615 Compare November 18, 2026 11:47
@jasnell
jasnell requested a review from addaleax November 18, 2026 12:21
@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.72%. Comparing base (528ff04) to head (42ecb47).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main   #67571      +/-   ##
==========================================
+ Coverage   90.70%   90.72%   +0.02%     
==========================================
  Files         801      801              
  Lines      280726   280811      +85     
  Branches    54180    54224      +44     
==========================================
+ Hits       254634   254776     +142     
+ Misses      16259    16205      -54     
+ Partials     9833     9830       -3     
Files with missing lines Coverage Δ
src/node_api.cc 77.12% <100.00%> (+0.02%) ⬆️
src/node_binding.cc 76.78% <100.00%> (+0.06%) ⬆️

... and 46 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Signed-off-by: René Larch <renelarch@gmail.com>
@r-Larch

r-Larch commented Nov 18, 2026

Copy link
Copy Markdown
Author

@2246250622 Thanks for the review,
The test case you suggested is a good idea.
I've added it as LocallyDefinedLinkedBindingExportsThenThrowsTest in b3e3a70.
The binding sets module.exports and then throws, and the test checks that _linkedBinding() throws init failed instead of returning those exports.
It fails on main without the fix and passes with it.

r-Larch added a commit to r-Larch/node-api-dotnet that referenced this pull request Nov 19, 2026
With LibNode 26 the error thrown by a linked module's init function no
longer reaches the caller of process._linkedBinding(): Node.js
GetLinkedBinding() reads module.exports after the init function returns,
and that V8 API call clears the pending exception. This affects every
linked binding and is fixed in nodejs/node#67571.

The test now checks that the error does not stay pending on the
runtime's env, which fails without moving it to the module's env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Return right after the register function when it left an exception
pending, instead of catching and rethrowing it with a TryCatch. This
keeps the code structure of main and matches the check in
napi_module_register_by_symbol.

Signed-off-by: René Larch <renelarch@gmail.com>
When a Node-API module's init function throws and returns an object
other than the exports it received, napi_module_register_by_symbol()
sets module.exports to that object. That V8 API call clears the pending
exception, so require() of such an addon returned the new exports
instead of throwing, and process._linkedBinding() did the same for a
linked Node-API binding. Return before setting module.exports when the
init function left an exception pending.

Signed-off-by: René Larch <renelarch@gmail.com>
@r-Larch r-Larch changed the title src: rethrow linked binding initializer errors src,node-api: keep initializer errors of linked bindings and addons Nov 19, 2026
@r-Larch

r-Larch commented Nov 19, 2026

Copy link
Copy Markdown
Author

Following @vmoroz's suggestion in microsoft/node-api-dotnet#512 (comment)
I've changed the PR to adopt his changes from microsoft/v8-jsi#289

The TryCatch and ReThrow() are gone in favor of a HasPendingException() check right after the initializer, in GetLinkedBinding() and in napi_module_register_by_symbol(). It's simpler and covers a case the TryCatch missed: a Node-API init that throws and returns new exports loses the error when module.exports is set, before GetLinkedBinding() runs. That also fixes require() of such an addon. There are new tests for both (a cctest and test/node-api/test_init_exception).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants