Errors

There are two types of errors:

• UserError: Thrown from actors and safely returned to clients with full details
• Internal errors: All other errors that are converted to a generic error message for security

Throwing and Catching Errors

UserError lets you throw custom errors that will be safely returned to the client.

Throw a UserError with just a message:

<Tabs> <Tab title="Actor"> <CodeSnippet file="examples/docs/actors-errors/throwing-actor.ts" /> </Tab> <Tab title="Client (Connection)"> <CodeSnippet file="examples/docs/actors-errors/throwing-client-connection.ts" /> </Tab> <Tab title="Client (Stateless)"> <CodeSnippet file="examples/docs/actors-errors/throwing-client-stateless.ts" /> </Tab> </Tabs>

Error Codes

Use error codes for explicit error matching in try-catch blocks:

<Tabs> <Tab title="Actor"> <CodeSnippet file="examples/docs/actors-errors/error-codes-actor.ts" /> </Tab> <Tab title="Client (Connection)"> <CodeSnippet file="examples/docs/actors-errors/error-codes-client-connection.ts" /> </Tab> <Tab title="Client (Stateless)"> <CodeSnippet file="examples/docs/actors-errors/error-codes-client-stateless.ts" /> </Tab> </Tabs>

Errors With Metadata

Include metadata to provide additional context for rich error handling:

<Tabs> <Tab title="Actor"> <CodeSnippet file="examples/docs/actors-errors/metadata-actor.ts" /> </Tab> <Tab title="Client (Connection)"> <CodeSnippet file="examples/docs/actors-errors/metadata-client-connection.ts" /> </Tab> <Tab title="Client (Stateless)"> <CodeSnippet file="examples/docs/actors-errors/metadata-client-stateless.ts" /> </Tab> </Tabs>

Internal Errors

All errors that are not UserError instances are automatically converted to a generic "internal error" response. This prevents accidentally leaking sensitive information like stack traces, database details, or internal system information.

<Tabs> <Tab title="Actor"> <CodeSnippet file="examples/docs/actors-errors/internal-actor.ts" /> </Tab> <Tab title="Client (Connection)"> <CodeSnippet file="examples/docs/actors-errors/internal-client-connection.ts" /> </Tab> <Tab title="Client (Stateless)"> <CodeSnippet file="examples/docs/actors-errors/internal-client-stateless.ts" /> </Tab> </Tabs>

Server-Side Logging

All internal errors are logged server-side with full details. When an internal error occurs, the complete error message, stack trace, and context are written to your server logs. This is where you should look first when debugging internal errors in production.

The client receives only a generic "Internal error" message for security, but you can find the full error details in your server logs including:

• Complete error message
• Stack trace
• Request context (actor ID, action name, connection ID, etc.)
• Timestamp

Always check your server logs to see the actual error details when debugging internal errors.

Exposing Errors to Clients (Development Only)

Warning: Only enable error exposure in development environments. In production, this will leak sensitive internal details to clients.

For faster debugging during development, you can expose internal error details to clients by setting RIVET_EXPOSE_ERRORS=1.

With error exposure enabled, clients will see the full error message instead of the generic "Internal error" response:

<CodeSnippet file="examples/docs/actors-errors/expose-errors.ts" />

API Reference

• UserError - User-facing error class
• ActorError - Errors received by the client