chore(rivetkit): RIVET_EXPOSE_ERRORS

[NathanFlurry]

No description provided.

[vercel]

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

Project	Deployment	Review	Updated (UTC)
rivet-site	Ready	Preview, Comment	Jan 6, 2026 2:34am
rivetkit-serverless	Error		Jan 6, 2026 2:34am

2 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
rivet-cloud	Ignored		Jan 6, 2026 2:34am
rivet-inspector	Ignored	Preview	Jan 6, 2026 2:34am

[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(engine): return error for pending actors #3730 : 2 dependent PRs (#3675 , #3740 )
• chore(gas): add support for find_workflows #3739
• chore(docs): document abort signal #3673
• chore(rivetkit): clean up logging configuration #3672
• chore(rivetkit): RIVET_EXPOSE_ERRORS #3671 👈 (View in Graphite)
• chore(rivetkit): specialize context types for better compiler errors #3669
• fix(rivetkit): fix c.client not respecting correct origin #3668
• fix(rivetkit): allow providing no args to createRivetKit #3667
• 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.

[claude]

PR Review: RIVET_EXPOSE_ERRORS Environment Variable

Summary

This PR implements the RIVET_EXPOSE_ERRORS environment variable feature that allows internal error details to be exposed to clients during development. The implementation is clean and follows the codebase patterns well.

✅ Strengths

1. Good documentation: The website documentation in website/src/content/docs/actors/errors.mdx is comprehensive and clearly explains:

   • When to use this feature (development only)
   • Security warnings about not using in production
   • How it works with NODE_ENV=development

2. Consistent implementation: The same logic is applied in both places:

   • rivetkit-typescript/packages/rivetkit/src/actor/protocol/old.ts:291-292
   • rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts:206-209

3. Clear function documentation: Good JSDoc comment added to getRequestExposeInternalError explaining its behavior

4. Security-conscious: The documentation appropriately warns users about the security implications

🔍 Issues & Suggestions

1. Critical: Inconsistent Parameter Usage ⚠️

In router-endpoints.ts:205, the _req parameter is prefixed with underscore indicating it's unused:

export function getRequestExposeInternalError(_req: Request): boolean {

However, this function should potentially use the request object to check for request-specific overrides or context. If the parameter is truly not needed, consider:

• Removing it entirely for clarity
• Adding a comment explaining why it exists but isn't used (perhaps for future extensibility)

Location: rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts:205

2. Potential: Environment Variable Caching

The getEnvUniversal() function is called twice on every error (and potentially many times during high error scenarios). Consider caching these environment variable reads at module initialization:

const EXPOSE_ERRORS = getEnvUniversal("RIVET_EXPOSE_ERRORS") === "1";
const IS_DEVELOPMENT = getEnvUniversal("NODE_ENV") === "development";

export function getRequestExposeInternalError(_req: Request): boolean {
    return EXPOSE_ERRORS || IS_DEVELOPMENT;
}

Benefit: Reduces overhead during error handling paths
Trade-off: Environment changes wouldn't be picked up without restart (but this is likely acceptable for these specific variables)

3. Documentation: Missing Security Best Practices

The documentation warns about not using in production, but could be strengthened with:

• Explicit recommendation to use environment-specific configuration
• Example of how to ensure it's disabled in production (e.g., in deployment configs)
• Warning about what sensitive information might be exposed (database connection strings, internal paths, etc.)

Location: website/src/content/docs/actors/errors.mdx:345-347

4. Code Duplication

The same boolean logic appears in two places:

• rivetkit-typescript/packages/rivetkit/src/actor/protocol/old.ts:291-292
• rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts:206-209

The first location could call getRequestExposeInternalError() instead of duplicating the logic:

// In old.ts:291-292
getRequestExposeInternalError(/* need to pass request */),

However, this would require access to the request object. If that's not available, consider extracting the boolean check into a separate utility function.

5. Minor: Typo in Previous Code

The old code had a typo: "Unipmlemented" → while this is fixed in the PR, it's worth noting it was there.

🧪 Testing Recommendations

This PR lacks tests. Consider adding:

1. Unit tests for getRequestExposeInternalError():

   • Returns false when neither env var is set
   • Returns true when RIVET_EXPOSE_ERRORS=1
   • Returns true when NODE_ENV=development
   • Returns true when both are set

2. Integration tests for error exposure:

   • Internal errors show generic message when env vars not set
   • Internal errors show detailed message when RIVET_EXPOSE_ERRORS=1
   • Internal errors show detailed message when NODE_ENV=development

Example test structure:

describe('getRequestExposeInternalError', () => {
  it('should return false by default', () => {
    // Test with clean environment
  });

  it('should return true when RIVET_EXPOSE_ERRORS=1', () => {
    // Test with env var set
  });

  it('should return true when NODE_ENV=development', () => {
    // Test with dev environment
  });
});

📋 Security Considerations

✅ Good: Clear warnings in documentation about production usage
⚠️ Consider:

• Could add runtime warning logs when RIVET_EXPOSE_ERRORS=1 is detected on startup
• Consider adding a check that prevents both production NODE_ENV and EXPOSE_ERRORS from being active simultaneously

🎯 Performance Considerations

• Minor: Repeated getEnvUniversal() calls in hot path (error handling)
• Suggestion: Cache environment variable reads (see Issue [SVC-2479] Send cluster events to PostHog #2 above)

✨ Code Quality

• Style: Follows existing patterns ✅
• Naming: Clear and descriptive ✅
• Documentation: Good JSDoc comment added ✅
• Consistency: Matches codebase conventions ✅

📝 Recommendations

Must Fix:

• None (code is functional)

Should Fix:

1. Add unit tests for getRequestExposeInternalError()
2. Consider caching environment variable reads
3. Address the unused _req parameter (remove or document why it exists)

Nice to Have:

1. Reduce code duplication between old.ts and router-endpoints.ts
2. Add runtime warning when error exposure is enabled
3. Enhance documentation with deployment best practices

Conclusion

This is a solid PR that implements a useful development feature. The code is clean, well-documented, and follows the project's patterns. The main areas for improvement are:

1. Adding test coverage
2. Minor performance optimization through caching
3. Addressing the unused parameter

The PR is ready to merge with the understanding that tests should be added in a follow-up (or before merge, if the team requires test coverage).

Approval: ✅ Approved with suggestions

[graphite-app]

Merge activity

• Jan 6, 2:19 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:20 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:20 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:21 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:22 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:22 AM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #3667.
• Jan 6, 2:31 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 6, 2:31 AM UTC: CI is running for this pull request on a draft pull request (#3754) due to your merge queue CI optimization settings.
• Jan 6, 2:32 AM UTC: Merged by the Graphite merge queue via draft PR: #3754.