fix(rivetkit): standardize error metadata return type

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 10, 2025 9:09pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 10, 2025 9:09pm
rivet-inspector	Ignored	Preview		Nov 10, 2025 9:09pm
rivet-site	Ignored	Preview		Nov 10, 2025 9:09pm

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(site): add typedoc docs #3446
• chore(rivetkit): remove deprecated packages #3447
• chore(rivetkit): add support for conn params on onRequest and onWebSocket #3445
• feat(rivetkit): add asyncapi spec #3442
• chore(rivetkit): add actor router to the openapi spec #3441
• fix(rivetkit): skip sending RivetKit messages to conns that do not support it #3440
• fix(rivetkit): fix race condition with websocket open events #3439
• fix(rivetkit): standardize error metadata return type #3438 👈 (View in Graphite)
• fix(rivetkit): remove incorrect getEndpoint call in metadata handler #3433
• feat(rivetkit): add json protocol support #3432
• chore(rivetkit): add required zod validation for json encoding #3431
• chore(rivetkit): add listing actors by only name to manager api #3430
• refactor(rivetkit): extract WebSocket protocol parsing to shared utility #3429
• refactor(rivetkit): restructure connection lifecycle contexts #3428
• chore(rivetkit): add WebSocketContext and RequestContext #3427
• chore(rivetkit): add conn type #3426
• chore(rivetkit): add connection for raw http #3425
• chore(rivetkit): rename onFetch to onRequest #3424
• refactor(rivetkit): add state manager for conn with symbol-based access #3423
• fix(rivetkit): use loggerWithoutContext for websocket error when actor undefined #3412
• feat(rivetkit): add GET /actors/names #3411
• feat(api-public): expose actor kv api #3410
• chore(rivetkit): auto-generate inspector token for engine driver #3409
• chore(rivetkit): close websockets on out of sequence messages #3404
• fix(rivetkit): properly apply clientEndpoint from metadata lookup #3402
• fix(rivetkit): properly handle msgIndex for hibernatable websocket reconnection #3401
• chore(rivetkit): rename onstart/onstop to onwake/onsleep #3422
• chore(rivetkit): split ActorInstance logic in to multiple classes #3421
• chore(rivetkit): move conns to separate persisted kv keys #3420
• chore(rivetkit): remove deprecated conn tokens & sse support #3419
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pkg-pr-new]

More templates

• example-ai-agent
• example-background-jobs
• example-better-auth-external-db
• example-bots
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-counter
• example-counter-serverless
• example-crdt
• example-cursors
• example-cursors-raw-websocket
• example-database
• example-deno
• example-sqlite
• example-elysia
• example-express
• example-freestyle
• example-game
• example-hono
• example-hono-bun
• example-hono-react
• example-kitchen-sink
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc
• example-workflows

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/actor@3438

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3438

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/core@3438

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3438

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3438

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3438

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3438

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3438

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3438

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3438

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3438

commit: 4599c4a

[claude]

Code Review: Standardize Error Metadata Return Type

Summary

This PR improves the consistency of error metadata handling by changing it from nullable to optional (TypeScript undefined vs null). This is a good change that aligns with TypeScript best practices and the BARE protocol specification.

Positive Aspects

1. Protocol Alignment: The change correctly aligns with the BARE protocol schema which uses optional for the metadata field in both v1.bare and v2.bare.

2. TypeScript Best Practices: Using undefined for optional fields is more idiomatic in TypeScript than using null. This avoids the confusion of having both null and undefined representing no value.

3. Consistent Handling: The PR updates all the serialization/deserialization paths consistently across JSON protocol, BARE/CBOR protocol, and client-side deserialization.

4. Careful Implementation: The conditional logic to only include metadata when defined prevents serializing undefined values in JSON, which is correct behavior.

Code Quality Observations

Good Practices

• The comments explaining the different serialization strategies are helpful
• The use of any type for the temporary val object is pragmatic given the conditional property assignment

Minor Concerns

1. Type Safety: The use of any on line 304 in old.ts could be improved with a more specific type.

2. Inconsistent Nullability Check: On line 332, the truthy check would treat empty strings, 0, false, etc. as no metadata. Consider using an explicit !== undefined check instead.

3. Similar Pattern in router.ts: Line 92-94 in router.ts has the same truthy check issue.

Test Coverage Concerns

Critical Gap: There are no tests that specifically validate error metadata handling. Recommended test cases:

• Verify errors with undefined metadata are serialized correctly
• Test errors with actual metadata values
• Validate the JSON vs BARE/CBOR serialization differences
• Confirm client-side deserialization handles both null and undefined correctly
• Test falsy metadata values like 0, false, empty string

Recommendations

1. High Priority: Add test coverage for error metadata handling, especially around the undefined vs null semantics
2. Medium Priority: Change truthy checks to explicit !== undefined checks to properly handle falsy metadata values
3. Low Priority: Consider strengthening the type of val on line 304 if possible

Conclusion

This is a solid improvement that makes the codebase more consistent and aligns with TypeScript conventions. The main concern is the lack of test coverage for this critical change in behavior. Consider adding tests before merging to prevent regressions.

Approval Status: Approve with recommendation to add tests