Thursday, 19 November 2026

Shola Jegede
← All packages

Database

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-sentry
344downloads last week
344downloads last 12 months
v0.0.0latest, Nov 17, 2026
2releases since Nov 17, 2026

Downloads

Download history

Loading download history…

Build this

Build with convex-sentry

  1. 1

    Install

    bash
    npm install convex-sentry

    Requirements: 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. 2

    Quick Start

    1. Add the component

    In convex/convex.config.ts:

    ts
    import { 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:

    bash
    npx 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:

    ts
    import { 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 sentry from this file wherever you capture.

  3. 3

    Usage

    Capture a handled error

    ts
    try {
      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 dropped

    captureException reads the error's stack (source-mapped by Convex), follows its cause chain, and adds a ConvexError's data to the event's extra data.

    Capture a message

    ts
    await sentry.captureMessage(ctx, `Checkout took ${durationMs}ms`, {
      level: "warning",
      extra: { durationMs, budgetMs: 1500 },
    });

    Messages default to the info level.

    Capture and rethrow in an action

    ts
    export 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, withSentry captures the error with handled: false and rethrows it, so the caller still sees the failure.

    Send an event to another project

    ts
    await sentry.captureException(ctx, error, {
      dsn: process.env.SENTRY_DSN_BILLING,
    });

    Read events and issues reactively

    ts
    export 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

    ts
    export const retryEvent = mutation({
      args: { eventId: v.string() },
      handler: async (ctx, args) => await sentry.retry(ctx, args),
    });