fix: preserve causes when wrapping render errors

CHANGELOG.md

@@ -34,6 +34,7 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Fixed
 
+- **Server-render error wrapping preserves original causes**: When server rendering catches a non-`Error` thrown value, React on Rails now wraps it with the original value attached as `cause`, making downstream debugging preserve more context. Fixes [Issue 1746](https://github.com/shakacode/react_on_rails/issues/1746). [PR 3230](https://github.com/shakacode/react_on_rails/pull/3230) by [justin808](https://github.com/justin808).
 - **[Pro]** **Node renderer now exposes `performance` when `supportModules: true`**: React 19's development build of `React.lazy` calls `performance.now()`, which previously threw `ReferenceError: performance is not defined` inside the node renderer's VM context unless users manually added `performance` via `additionalContext`. `performance` is now included in the default globals alongside `Buffer`, `process`, etc. Fixes [Issue 3154](https://github.com/shakacode/react_on_rails/issues/3154). [PR 3158](https://github.com/shakacode/react_on_rails/pull/3158) by [justin808](https://github.com/justin808).
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).
 - **Doctor accepts TypeScript server bundle entrypoints**: `react_on_rails:doctor` now resolves common source entrypoint suffixes (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`) before warning that the server bundle is missing, preventing false positives when apps use `server-bundle.ts`. [PR 3111](https://github.com/shakacode/react_on_rails/pull/3111) by [justin808](https://github.com/justin808).

packages/react-on-rails-pro-node-renderer/tests/serverRenderRSCReactComponent.test.js

@@ -142,7 +142,9 @@ describe('serverRenderRSCReactComponent', () => {
 
     if (expectedError) {
       expect(onError).toHaveBeenCalled();
-      expect(onError).toHaveBeenCalledWith(new Error(expectedError));
+      const [emittedError] = onError.mock.calls[0];
+      expect(Object.prototype.toString.call(emittedError)).toBe('[object Error]');
+      expect(emittedError.message).toBe(expectedError);
     }
 
     expectedContents.forEach((text) => {

packages/react-on-rails/src/serverRenderUtils.ts

@@ -24,8 +24,37 @@ export function createResultObject(
   };
 }
 
+function isCrossRealmError(e: unknown): e is { message?: unknown } {
+  return typeof e === 'object' && e !== null && Object.prototype.toString.call(e) === '[object Error]';
+}
+
+function stringifyThrownValue(e: unknown): string {
+  if (isCrossRealmError(e)) {
+    return typeof e.message === 'string' ? e.message : Object.prototype.toString.call(e);
+  }
+
+  if (typeof e === 'object' && e !== null) {
+    try {
+      // JSON.stringify can return undefined without throwing, for example when toJSON returns undefined.
+      return JSON.stringify(e) ?? Object.prototype.toString.call(e);
+    } catch {
+      return Object.prototype.toString.call(e);
+    }
+  }
+
+  return String(e);
+}
+
 export function convertToError(e: unknown): Error {
-  return e instanceof Error ? e : new Error(String(e));
+  if (e instanceof Error) {
+    return e;
+  }
+
+  const message = stringifyThrownValue(e);
+  // tsconfig uses es2020 libs, which do not type Error.cause even though supported runtimes provide it.
+  const error = new Error(message) as Error & { cause?: unknown };
+  error.cause = e;
+  return error;
 }
 
 export function validateComponent(componentObj: RegisteredComponent, componentName: string) {

packages/react-on-rails/tests/serverRenderUtils.test.ts

@@ -0,0 +1,90 @@
+import { Script } from 'node:vm';
+
+import { convertToError } from '../src/serverRenderUtils.ts';
+
+type ErrorWithCause = Error & { cause?: unknown };
+
+describe('serverRenderUtils', () => {
+  describe('convertToError', () => {
+    it('returns Error instances unchanged', () => {
+      const error = new Error('Already an error');
+
+      expect(convertToError(error)).toBe(error);
+    });
+
+    it('wraps plain object thrown values with a readable message while preserving the original cause', () => {
+      const thrownValue = { message: 'plain object failure' };
+
+      const error = convertToError(thrownValue);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('{"message":"plain object failure"}');
+      expect((error as ErrorWithCause).cause).toBe(thrownValue);
+    });
+
+    it('wraps a thrown string with the string as the message and cause', () => {
+      const error = convertToError('something went wrong');
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('something went wrong');
+      expect((error as ErrorWithCause).cause).toBe('something went wrong');
+    });
+
+    it('wraps a thrown number', () => {
+      const error = convertToError(42);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('42');
+      expect((error as ErrorWithCause).cause).toBe(42);
+    });
+
+    it('wraps null thrown values', () => {
+      const error = convertToError(null);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('null');
+      expect((error as ErrorWithCause).cause).toBeNull();
+    });
+
+    it('wraps undefined thrown values', () => {
+      const error = convertToError(undefined);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('undefined');
+      expect((error as ErrorWithCause).cause).toBeUndefined();
+    });
+
+    it('wraps circular-reference objects without throwing', () => {
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+
+      const error = convertToError(circular);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('[object Object]');
+      expect((error as ErrorWithCause).cause).toBe(circular);
+    });
+
+    it('wraps errors thrown from another JavaScript realm with their original message', () => {
+      const thrownValue: unknown = new Script('new Error("cross-realm failure")').runInNewContext();
+
+      const error = convertToError(thrownValue);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('cross-realm failure');
+      expect((error as ErrorWithCause).cause).toBe(thrownValue);
+    });
+
+    it('wraps cross-realm errors with non-string messages using the error tag', () => {
+      const thrownValue: unknown = new Script(
+        'const error = new Error(); error.message = 42; error',
+      ).runInNewContext();
+
+      const error = convertToError(thrownValue);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('[object Error]');
+      expect((error as ErrorWithCause).cause).toBe(thrownValue);
+    });
+  });
+});