Thursday, 19 November 2026
Shola JegedeDatabase
convex-sentry
Report handled errors and messages from Convex mutations and actions to Sentry, through a durable outbox with retries, dedupe, and a reactive local error feed.
npm install convex-sentryDownloads
Download history
Build this
Build with convex-sentry
- 1
Install
bashnpm install convex-sentryRequirements: Convex v1.34.1 or later, and a Sentry project (sentry.io or self-hosted) if you want events sent anywhere. Without one, events stay in Convex.
- 2
Quick Start
1. Add the component
In
convex/convex.config.ts:tsimport { defineApp } from "convex/server"; import convexSentry from "convex-sentry/convex.config"; const app = defineApp(); app.use(convexSentry); export default app;2. Set your DSN
Copy the DSN from your Sentry project's Settings > Client Keys (DSN) page:
bashnpx convex env set SENTRY_DSN https://<key>@<org>.ingest.sentry.io/<project>When you create the Sentry project, pick JavaScript or Node.js as the platform.
3. Create the client
In
convex/sentry.ts:tsimport { components } from "./_generated/api"; import { Sentry } from "convex-sentry"; export const sentry = new Sentry(components.convexSentry, { dsn: process.env.SENTRY_DSN, environment: process.env.SENTRY_ENVIRONMENT ?? "production", });Import
sentryfrom this file wherever you capture. - 3
Usage
Capture a handled error
tstry { await chargeCard(ctx, args); } catch (error) { await sentry.captureException(ctx, error, { functionName: "billing:charge", level: "warning", tags: { feature: "billing" }, extra: { invoiceId: args.invoiceId }, user: { id: userId }, breadcrumbs: [ { category: "billing", message: "Retrying with backup card" }, ], }); } // Returns: the Sentry event id, or null if the event was sampled out or droppedcaptureExceptionreads the error's stack (source-mapped by Convex), follows itscausechain, and adds aConvexError'sdatato the event's extra data.Capture a message
tsawait sentry.captureMessage(ctx, `Checkout took ${durationMs}ms`, { level: "warning", extra: { durationMs, budgetMs: 1500 }, });Messages default to the
infolevel.Capture and rethrow in an action
tsexport const syncInventory = action({ args: { sku: v.string() }, handler: async (ctx, args) => await sentry.withSentry( ctx, async () => { const res = await fetch(`https://supplier.example/stock/${args.sku}`); if (!res.ok) throw new Error(`Supplier responded ${res.status}`); return await res.json(); }, { functionName: "inventory:sync" }, ), });If the callback throws,
withSentrycaptures the error withhandled: falseand rethrows it, so the caller still sees the failure.Send an event to another project
tsawait sentry.captureException(ctx, error, { dsn: process.env.SENTRY_DSN_BILLING, });Read events and issues reactively
tsexport const recentErrors = query({ args: {}, handler: async (ctx) => await sentry.listEvents(ctx, { limit: 20 }), }); export const failedDeliveries = query({ args: {}, handler: async (ctx) => await sentry.listEvents(ctx, { status: "failed" }), }); export const issues = query({ args: {}, handler: async (ctx) => await sentry.listGroups(ctx), });Retry a failed delivery
tsexport const retryEvent = mutation({ args: { eventId: v.string() }, handler: async (ctx, args) => await sentry.retry(ctx, args), });