fix(rivetkit): keep UserErrors intact when their metadata is not JSON

Author: eersnington

rivetkit-typescript/packages/rivetkit/fixtures/driver-test-suite/error-handling.ts

@@ -21,6 +21,14 @@ export const errorHandlingActor = actor({
 			});
 		},
 
+		// Action that throws a UserError whose metadata JSON cannot encode
+		throwBigintMetadataError: () => {
+			throw new UserError("Card declined", {
+				code: "card_declined",
+				metadata: { amountCents: 1999n },
+			});
+		},
+
 		// Action that throws an internal error
 		throwInternalError: () => {
 			throw new Error("This is an internal error");

rivetkit-typescript/packages/rivetkit/fixtures/driver-test-suite/telemetry.ts

@@ -123,7 +123,10 @@ export const telemetryRunConsumerActor = actor({
 	actions: {},
 });
 
-/** Waits for two messages and logs when it sleeps, so a test can send the second one after the sleep. */
+/**
+ * Waits for two messages and logs when it sleeps, so a test can send the second one after the sleep.
+ * The declined charge carries `bigint` metadata, which JSON cannot encode.
+ */
 export const workflowTracedActor = actor({
 	state: { chargeAttempts: 0, wakes: 0 },
 	db: db(),
@@ -157,6 +160,7 @@ export const workflowTracedActor = actor({
 				if (c.state.chargeAttempts <= 2) {
 					throw new UserError("card declined", {
 						code: "card_declined",
+						metadata: { amountCents: 1999n },
 					});
 				}
 			},

rivetkit-typescript/packages/rivetkit/src/actor/errors.ts

@@ -244,8 +244,21 @@ export function toRivetError(
 	);
 }
 
-export function encodeBridgeRivetError(error: RivetErrorLike): string {
-	return `${BRIDGE_RIVET_ERROR_PREFIX}${JSON.stringify({
+/** A structured error encoded for the bridge to Core. */
+export interface EncodedBridgeError {
+	readonly encoded: string;
+	/** Set when JSON could not encode the metadata, which was dropped. */
+	readonly droppedMetadataCause?: unknown;
+}
+
+/**
+ * Encodes a structured error for the bridge to Core. Metadata that JSON cannot
+ * encode, such as a `bigint`, is dropped so the error itself still crosses.
+ */
+export function encodeBridgeRivetError(
+	error: RivetErrorLike,
+): EncodedBridgeError {
+	const payload = {
 		group: error.group,
 		code: error.code,
 		message: error.message,
@@ -254,7 +267,17 @@ export function encodeBridgeRivetError(error: RivetErrorLike): string {
 		public: error.public,
 		statusCode: error.statusCode,
 		actor: error.actor,
-	})}`;
+	};
+	try {
+		return {
+			encoded: `${BRIDGE_RIVET_ERROR_PREFIX}${JSON.stringify(payload)}`,
+		};
+	} catch (cause) {
+		return {
+			encoded: `${BRIDGE_RIVET_ERROR_PREFIX}${JSON.stringify({ ...payload, metadata: undefined })}`,
+			droppedMetadataCause: cause,
+		};
+	}
 }
 
 /**
@@ -264,7 +287,7 @@ export function encodeBridgeRivetError(error: RivetErrorLike): string {
  */
 export function encodeErrorForBridge(error: unknown): string {
 	if (isCanonicalStructuredRivetError(error)) {
-		return encodeBridgeRivetError(error);
+		return encodeBridgeRivetError(error).encoded;
 	}
 	return String(error);
 }

rivetkit-typescript/packages/rivetkit/src/registry/native.ts

@@ -872,7 +872,19 @@ function encodeNativeCallbackError(error: unknown): Error {
 		? error
 		: deconstructError(error, true);
 
-	const bridgeError = new Error(encodeBridgeRivetError(structuredError), {
+	const { encoded, droppedMetadataCause } =
+		encodeBridgeRivetError(structuredError);
+	if (droppedMetadataCause !== undefined) {
+		logger().warn(
+			{
+				group: structuredError.group,
+				code: structuredError.code,
+				error: String(droppedMetadataCause),
+			},
+			"dropped error metadata that JSON cannot encode",
+		);
+	}
+	const bridgeError = new Error(encoded, {
 		cause: error instanceof Error ? error : undefined,
 	});
 	return Object.assign(bridgeError, {

rivetkit-typescript/packages/rivetkit/tests/driver/actor-error-handling.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import {
 	INTERNAL_ERROR_CODE,
 	INTERNAL_ERROR_DESCRIPTION,
@@ -48,6 +48,34 @@ describeDriverMatrix("Actor Error Handling", (driverTestConfig) => {
 					expect(error.metadata.timestamp).toBeDefined();
 				}
 			});
+
+			test("returns the UserError without metadata JSON cannot encode and logs the drop", async (c) => {
+				const { client, getRuntimeOutput } = await setupDriverTest(
+					c,
+					driverTestConfig,
+				);
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				const error = await handle.throwBigintMetadataError().then(
+					() => undefined,
+					(error: any) => error,
+				);
+
+				expect(error?.code).toBe("card_declined");
+				expect(error?.message).toBe("Card declined");
+				expect(error?.metadata).toBeUndefined();
+				// The runtime process writes its log through a pipe that can lag the action reply.
+				await vi.waitFor(() => {
+					const warning = getRuntimeOutput()
+						.split("\n")
+						.find((line) =>
+							line.includes(
+								"dropped error metadata that JSON cannot encode",
+							),
+						);
+					expect(warning).toContain("code=card_declined");
+				});
+			});
 		});
 
 		describe("Internal Error Handling", () => {

rivetkit-typescript/packages/rivetkit/tests/driver/actor-telemetry.test.ts

@@ -1174,7 +1174,7 @@ describeDriverMatrix(
 					expect(line).toContain(`rayId=${approveRayId}`);
 				});
 
-				test("reports each attempt of a retried step under its own run", () => {
+				test("reports each attempt of a retried step under its own run, even when the error metadata is not JSON", () => {
 					const attempts = named(`${actorName}/charge-card`);
 					expect(
 						attempts.map((attempt) => [

rivetkit-typescript/packages/rivetkit/tests/rivet-error.test.ts

@@ -23,7 +23,9 @@ describe("RivetError bridge helpers", () => {
 			},
 		});
 
-		const decoded = decodeBridgeRivetError(encodeBridgeRivetError(error));
+		const decoded = decodeBridgeRivetError(
+			encodeBridgeRivetError(error).encoded,
+		);
 
 		expect(decoded).toBeInstanceOf(RivetError);
 		expect(decoded).toMatchObject({