Loading components
convex-sentry lets you capture handled errors and messages from Convex mutations and actions to Sentry, with built-in retries, deduplication, and a reactive eve
npm install convex-sentryconvex-sentry adds `captureException` and `captureMessage` to Convex mutations and actions for handled errors that never reach Convex's built-in exception reporting. Each event is written to a component-isolated table within the caller's transaction, then delivered to Sentry via a scheduled action with exponential backoff, rate-limit-aware retries, and fingerprint-based deduplication. Events and grouped issues remain queryable and reactive through the component's query API.
convex-sentry provides a captureException method you call inside a catch block within a mutation. The event is written to a Convex table as part of the mutation's transaction, then a scheduled action delivers it to Sentry with retries. If the mutation rolls back, the event is rolled back too, so you never log errors from failed transactions.
convex-sentry exposes a withSentry wrapper for action handlers. Wrap your async function body with withSentry and it captures any thrown error as unhandled and rethrows it, so the caller still receives the failure while Sentry gets the event. You can also call captureException or captureMessage directly inside action catch blocks.
convex-sentry automatically retries delivery on network errors, 5xx responses, and 429 rate limits using exponential backoff and Sentry's X-Sentry-Rate-Limits or Retry-After headers. You can also manually retry a failed event by calling the retry method with the event ID from a mutation.
convex-sentry generates a fingerprint for each event based on the error type, normalized message, innermost stack frame in your code, and function name. Events with the same fingerprint within the dedupeWindowMs window are stored in Convex but only the first is sent to Sentry. You can set dedupeWindowMs to 0 to disable deduplication or pass a custom fingerprint array.
No. convex-sentry builds Sentry envelopes itself and posts them using the native fetch API, so it runs in the default Convex runtime without requiring the Sentry SDK or a Node.js environment directive.
The event is rolled back along with the rest of the mutation's writes because captureException writes to Convex as part of the same transaction. If you need to capture an error and still rethrow it from a mutation, the event will not be persisted. Use withSentry in actions for capture-and-rethrow patterns.
Yes. If you leave the DSN unset, convex-sentry stores all events in Convex with the status local and never attempts delivery. This works on any Convex plan and is useful for local development or for teams that want an internal error log without a Sentry subscription.
convex-sentry provides a cleanup method that deletes settled events older than a specified cutoff and removes groups not seen since that cutoff. Call cleanup from a Convex cron job, passing olderThanMs to control the retention window. It processes events in batches and schedules itself until all old records are removed.
No. convex-sentry is designed for handled errors that you catch inside your functions. Convex's built-in exception reporting covers uncaught errors that escape a function. The two work independently, and the README recommends keeping the built-in integration enabled for uncaught errors.