triggerdotdev--trigger.dev/docs/guides/examples/sentry-error-tracking.mdx

---
title: "Track errors with Sentry"
sidebarTitle: "Sentry error tracking"
description: "This example demonstrates how to track errors with Sentry using Trigger.dev."
---

## Overview

Automatically send errors and source maps to your Sentry project from your Trigger.dev tasks. Sending source maps to Sentry allows for more detailed stack traces when errors occur, as Sentry can map the minified code back to the original source code.

## Prerequisites

- A [Sentry](https://sentry.io) account and project
- A [Trigger.dev](https://trigger.dev) account and project

## Setup

This setup involves two files:

1. **`trigger.config.ts`** - Configures the build to upload source maps to Sentry during deployment
2. **`trigger/init.ts`** - Initializes Sentry and registers the error tracking hook at runtime

<Note>
  You will need to set the `SENTRY_AUTH_TOKEN` and `SENTRY_DSN` environment variables. You can find
  the `SENTRY_AUTH_TOKEN` in your Sentry dashboard, in settings -> developer settings -> auth tokens
  and the `SENTRY_DSN` in your Sentry dashboard, in settings -> projects -> your project -> client
  keys (DSN). Add these to your `.env` file, and in your [Trigger.dev
  dashboard](https://cloud.trigger.dev), under environment variables in your project's sidebar.
</Note>

### Build configuration

Add this build configuration to your `trigger.config.ts` file. This uses the Sentry esbuild plugin to upload source maps every time you deploy your project.

```ts trigger.config.ts
import { defineConfig } from "@trigger.dev/sdk";
import { esbuildPlugin } from "@trigger.dev/build/extensions";
import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    extensions: [
      esbuildPlugin(
        sentryEsbuildPlugin({
          org: "<your-sentry-org>",
          project: "<your-sentry-project>",
          // Find this auth token in settings -> developer settings -> auth tokens
          authToken: process.env.SENTRY_AUTH_TOKEN,
        }),
        { placement: "last", target: "deploy" }
      ),
    ],
  },
});
```

<Note>
  [Build extensions](/config/extensions/overview) allow you to hook into the build system and
  customize the build process or the resulting bundle and container image (in the case of
  deploying). You can use pre-built extensions or create your own.
</Note>

### Bun runtime

If you are using the Bun runtime, esbuild's bundling of `@sentry/node`'s CJS entry can cause a runtime error in the local dev environment. Add the following extension to mark `@sentry/node` as external in dev only:

```ts trigger.config.ts
import { defineConfig } from "@trigger.dev/sdk";
import { esbuildPlugin } from "@trigger.dev/build/extensions";
import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";

export default defineConfig({
  project: "<project ref>",
  runtime: "bun",
  build: {
    extensions: [
      {
        name: "sentry-external-dev",
        externalsForTarget: (target) => (target === "dev" ? ["@sentry/node"] : []),
      },
      esbuildPlugin(
        sentryEsbuildPlugin({
          org: "<your-sentry-org>",
          project: "<your-sentry-project>",
          authToken: process.env.SENTRY_AUTH_TOKEN,
        }),
        { placement: "last", target: "deploy" }
      ),
    ],
  },
});
```

This lets Bun resolve `@sentry/node` directly from `node_modules` during dev, while still bundling it normally for deployment.

### Runtime initialization

Create a `trigger/init.ts` file to initialize Sentry and register the global `onFailure` hook. This file is automatically loaded when your tasks execute.

```ts trigger/init.ts
import { tasks } from "@trigger.dev/sdk";
import * as Sentry from "@sentry/node";

// Initialize Sentry
Sentry.init({
  defaultIntegrations: false,
  // The Data Source Name (DSN) is a unique identifier for your Sentry project.
  dsn: process.env.SENTRY_DSN,
  // Update this to match the environment you want to track errors for
  environment: process.env.NODE_ENV === "production" ? "production" : "development",
});

// Register a global onFailure hook to capture errors
tasks.onFailure(({ payload, error, ctx }) => {
  Sentry.captureException(error, {
    extra: {
      payload,
      ctx,
    },
  });
});
```

<Note>
  Learn more about [global lifecycle hooks](/tasks/overview#global-lifecycle-hooks) and the
  [`init.ts` file](/tasks/overview#init-ts).
</Note>

## Testing that errors are being sent to Sentry

To test that errors are being sent to Sentry, you need to create a task that will fail.

This task takes no payload, and will throw an error.

```ts trigger/sentry-error-test.ts
import { task } from "@trigger.dev/sdk";

export const sentryErrorTest = task({
  id: "sentry-error-test",
  retry: {
    // Only retry once
    maxAttempts: 1,
  },
  run: async () => {
    const error = new Error("This is a custom error that Sentry will capture");
    error.cause = { additionalContext: "This is additional context" };
    throw error;
  },
});
```

After creating the task, deploy your project.

 <CodeGroup>

    ```bash npm
    npx trigger.dev@latest deploy
    ```

    ```bash pnpm
    pnpm dlx trigger.dev@latest deploy
    ```

    ```bash yarn
    yarn dlx trigger.dev@latest deploy
    ```

    </CodeGroup>

Once deployed, open the `sentry-error-test` task in your [Trigger.dev dashboard](https://cloud.trigger.dev) (make sure you're in your `prod` environment) and press the "Test" button to open the test page for it.

Run a test task with an empty payload by clicking the `Run test` button.

Your run should then fail, and if everything is set up correctly, you will see an error in the Sentry project dashboard shortly after.