From 64670a3d9c24698f75f1165704620911065c0f48 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Tue, 10 Mar 2026 17:12:31 +0100
Subject: [PATCH 1/2] repl: add customizable error handling

Whether or not an exception should be handled when it
was thrown in the REPL's context but the REPL is already
closed is something that will depend on the details of
the specific REPL instance's use case.

Adding this option lets the REPL's creator control the
details of this behavior.

This resolves a TODO recently added in bd3cba5633e8a36.
---
 doc/api/repl.md                               | 14 ++++
 lib/repl.js                                   | 25 ++++--
 test/parallel/test-repl-user-error-handler.js | 84 +++++++++++++++++++
 3 files changed, 116 insertions(+), 7 deletions(-)
 create mode 100644 test/parallel/test-repl-user-error-handler.js

diff --git a/doc/api/repl.md b/doc/api/repl.md
index 0ebd5ca4e6f465..2ed7679ecf7245 100644
--- a/doc/api/repl.md
+++ b/doc/api/repl.md
@@ -709,6 +709,9 @@ npx codemod@latest @nodejs/repl-builtin-modules
 <!-- YAML
 added: v0.1.91
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62188
+    description: The `handleError` parameter has been added.
   - version: v24.1.0
     pr-url: https://github.com/nodejs/node/pull/58003
     description: Added the possibility to add/edit/remove multilines
@@ -787,6 +790,17 @@ changes:
     previews or not. **Default:** `true` with the default eval function and
     `false` in case a custom eval function is used. If `terminal` is falsy, then
     there are no previews and the value of `preview` has no effect.
+  * `handleError` {Function} This function customizes error handling in the REPL.
+    It receives the thrown exception as its first argument and must return one
+    of the following values synchronously:
+    * `'print'` to print the error to the output stream (default behavior).
+    * `'ignore'` to skip all remaining error handling.
+    * `'unhandled'` to treat the exception as fully unhandled. In this case,
+      the error will be passed to process-wide exception handlers, such as
+      the [`'uncaughtException'`][] event.
+    The `'unhandled'` value may or may not be desirable in situations
+    where the `REPLServer` instance has been closed, depending on the particular
+    use case.
 * Returns: {repl.REPLServer}
 
 The `repl.start()` method creates and starts a [`repl.REPLServer`][] instance.
diff --git a/lib/repl.js b/lib/repl.js
index e747cc581cc8eb..779740bfd411ad 100644
--- a/lib/repl.js
+++ b/lib/repl.js
@@ -125,6 +125,7 @@ const {
     ERR_INVALID_ARG_VALUE,
     ERR_INVALID_REPL_EVAL_CONFIG,
     ERR_INVALID_REPL_INPUT,
+    ERR_INVALID_STATE,
     ERR_MISSING_ARGS,
     ERR_SCRIPT_EXECUTION_INTERRUPTED,
   },
@@ -195,14 +196,9 @@ function setupExceptionCapture() {
 
   process.addUncaughtExceptionCaptureCallback((err) => {
     const store = replContext.getStore();
-    // TODO(addaleax): Add back a `store.replServer.closed` check here
-    // as a semver-major change.
-    // This check may need to allow for an opt-out, since the change in
-    // behavior could lead to DoS vulnerabilities (e.g. in the case of
-    // the net-based REPL described in our docs).
     if (store?.replServer) {
-      store.replServer._handleError(err);
-      return true; // We handled it
+      const result = store.replServer._handleError(err);
+      return result !== 'unhandled'; // We handled it
     }
     // No active REPL context - let other handlers try
   });
@@ -387,6 +383,7 @@ class REPLServer extends Interface {
     this.lastError = undefined;
     this.breakEvalOnSigint = !!options.breakEvalOnSigint;
     this.editorMode = false;
+    this._userErrorHandler = options.handleError;
     // Context id for use with the inspector protocol.
     this[kContextId] = undefined;
     this[kLastCommandErrored] = false;
@@ -987,6 +984,20 @@ class REPLServer extends Interface {
   }
   _handleError(e) {
     debug('handle error');
+    if (this._userErrorHandler) {
+      const state = this._userErrorHandler(e);
+      if (state !== 'ignore' && state !== 'print' && state !== 'unhandled') {
+        throw new ERR_INVALID_STATE(
+          'External REPL error handler must return either "ignore", "print"' +
+          `, or "unhandled", but received: ${state}`);
+      }
+      if (state === 'ignore') {
+        return;
+      }
+      if (state === 'unhandled') {
+        return 'unhandled';
+      }
+    }
     let errStack = '';
 
     if (typeof e === 'object' && e !== null) {
diff --git a/test/parallel/test-repl-user-error-handler.js b/test/parallel/test-repl-user-error-handler.js
new file mode 100644
index 00000000000000..31bd46b13d36d1
--- /dev/null
+++ b/test/parallel/test-repl-user-error-handler.js
@@ -0,0 +1,84 @@
+'use strict';
+const common = require('../common');
+const { start } = require('node:repl');
+const assert = require('node:assert');
+const { PassThrough } = require('node:stream');
+const { once } = require('node:events');
+const test = require('node:test');
+const { spawn } = require('node:child_process');
+
+function* generateCases() {
+  for (const async of [false, true]) {
+    for (const handleErrorReturn of ['ignore', 'print', 'unhandled', 'badvalue']) {
+      if (handleErrorReturn === 'badvalue' && async) {
+        // Handled through a separate test using a child process
+        continue;
+      }
+      yield { async, handleErrorReturn };
+    }
+  }
+}
+
+for (const { async, handleErrorReturn } of generateCases()) {
+  test(`async: ${async}, handleErrorReturn: ${handleErrorReturn}`, async () => {
+    let err;
+    const options = {
+      input: new PassThrough(),
+      output: new PassThrough().setEncoding('utf8'),
+      handleError: common.mustCall((e) => {
+        err = e;
+        queueMicrotask(() => repl.emit('handled-error'));
+        return handleErrorReturn;
+      })
+    };
+
+    let uncaughtExceptionEvent;
+    if (handleErrorReturn === 'unhandled' && async) {
+      process.removeAllListeners('uncaughtException'); // Remove the test runner's handler
+      uncaughtExceptionEvent = once(process, 'uncaughtException');
+    }
+
+    const repl = start(options);
+    const inputString = async ?
+      'setImmediate(() => { throw new Error("testerror") })\n42\n' :
+      'throw new Error("testerror")\n42\n';
+    if (handleErrorReturn === 'badvalue') {
+      assert.throws(() => options.input.end(inputString), /ERR_INVALID_STATE/);
+      return;
+    }
+    options.input.end(inputString);
+
+    await once(repl, 'handled-error');
+    assert.strictEqual(err.message, 'testerror');
+    const outputString = options.output.read();
+    assert.match(outputString, /42/);
+
+    if (handleErrorReturn === 'print') {
+      assert.match(outputString, /testerror/);
+    } else {
+      assert.doesNotMatch(outputString, /testerror/);
+    }
+
+    if (uncaughtExceptionEvent) {
+      const [uncaughtErr] = await uncaughtExceptionEvent;
+      assert.strictEqual(uncaughtErr, err);
+    }
+  });
+}
+
+test('async: true, handleErrorReturn: badvalue', async () => {
+  // Can't test this the same way as the other combinations
+  // since this will take the process down in a way that
+  // cannot be caught.
+  const proc = spawn(process.execPath, ['-e', `
+    require('node:repl').start({
+      handleError: () => 'badvalue'
+    })
+  `], { encoding: 'utf8', stdio: 'pipe' });
+  proc.stdin.end('throw new Error("foo");');
+  let stderr = '';
+  proc.stderr.setEncoding('utf8').on('data', (data) => stderr += data);
+  const [exit] = await once(proc, 'close');
+  assert.strictEqual(exit, 1);
+  assert.match(stderr, /ERR_INVALID_STATE.+badvalue/);
+});

From 64980e1658e6b560f0242624dd3e821dd6a8bfd6 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Tue, 10 Mar 2026 17:58:11 +0100
Subject: [PATCH 2/2] fixup! repl: add customizable error handling

---
 doc/api/repl.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/api/repl.md b/doc/api/repl.md
index 2ed7679ecf7245..c26b2a56dc8ad5 100644
--- a/doc/api/repl.md
+++ b/doc/api/repl.md
@@ -798,9 +798,9 @@ changes:
     * `'unhandled'` to treat the exception as fully unhandled. In this case,
       the error will be passed to process-wide exception handlers, such as
       the [`'uncaughtException'`][] event.
-    The `'unhandled'` value may or may not be desirable in situations
-    where the `REPLServer` instance has been closed, depending on the particular
-    use case.
+      The `'unhandled'` value may or may not be desirable in situations
+      where the `REPLServer` instance has been closed, depending on the particular
+      use case.
 * Returns: {repl.REPLServer}
 
 The `repl.start()` method creates and starts a [`repl.REPLServer`][] instance.