Next.js

Learn how to set up and configure Sentry in your Next.js application using the installation wizard, capture your first errors, logs and traces and view them in Sentry.

Agent-Assisted Setup

Use curl to download, read and follow https://skills.sentry.dev/instrument to set up the Sentry Next.js SDK.

Your agent will set up Sentry in your Next.js app automatically. Works with Cursor, Claude Code, Codex, and more.View docs ↗

Install the full plugin

Install the Sentry plugin to give your assistant every skill. See the installation docs for more details.

Copied

npx @sentry/agent-plugin install

You need:

A Next.js application
A Sentry account and project

Run the Sentry wizard to automatically configure Sentry in your Next.js application:

Copied

npx @sentry/wizard@latest -i nextjs

npx @sentry/wizard@latest -i nextjs

The wizard will prompt you to select features. Choose the ones you want to enable:

Error MonitoringTracingSession Replay

Prefer to set things up yourself? Check out the Manual Setup guide.

The wizard configured Sentry for all Next.js runtime environments and created files to test your setup.

Next.js runs code in different environments. The wizard creates separate initialization files for each:

Client (instrumentation-client.ts) — Runs in the browser
Server (sentry.server.config.ts) — Runs in Node.js
Edge (sentry.edge.config.ts) — Runs in edge runtimes

instrumentation-client.ts

Copied

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
});

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
  integrations: [
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
  ],
});

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
});

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
});

Adjust sample rates for production

The example above samples 100% of traces in development and 10% in production. Monitor your usage stats and adjust tracesSampleRate based on your traffic volume. Learn more about sampling configuration.

The instrumentation.ts file registers your server and edge configurations with Next.js.

instrumentation.ts

Copied

import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

export const onRequestError = Sentry.captureRequestError;

import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

export const onRequestError = Sentry.captureRequestError;

Your next.config.ts is wrapped with withSentryConfig to enable source map uploads, tunneling (to avoid ad-blockers), and other build-time features.

next.config.ts

Copied

import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Upload source maps for readable stack traces
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Route Sentry requests through your server (avoids ad-blockers)
  tunnelRoute: "/sentry-tunnel",

  silent: !process.env.CI,
});

import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Upload source maps for readable stack traces
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Route Sentry requests through your server (avoids ad-blockers)
  tunnelRoute: "/sentry-tunnel",

  silent: !process.env.CI,
});

The wizard creates app/global-error.tsx to capture React rendering errors in your App Router application.

app/global-error.tsx

Copied

"use client";

import * as Sentry from "@sentry/nextjs";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h1>Something went wrong!</h1>
      </body>
    </html>
  );
}

"use client";

import * as Sentry from "@sentry/nextjs";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h1>Something went wrong!</h1>
      </body>
    </html>
  );
}

The wizard creates .env.sentry-build-plugin with your auth token for source map uploads. This file is automatically added to .gitignore.

For CI/CD, set the SENTRY_AUTH_TOKEN environment variable in your build system.

.env.sentry-build-plugin

Copied

SENTRY_AUTH_TOKEN=sntrys_eyJ...

SENTRY_AUTH_TOKEN=sntrys_eyJ...

# Set as environment variable in your CI/CD system
SENTRY_AUTH_TOKEN=sntrys_eyJ...

The wizard creates /sentry-example-page with a button that triggers a test error. Use this to verify your setup.

Copied

app/
├── sentry-example-page/
│   └── page.tsx       # Test page with error button
└── api/
    └── sentry-example-api/
        └── route.ts   # Test API route

app/
├── sentry-example-page/
│   └── page.tsx       # Test page with error button
└── api/
    └── sentry-example-api/
        └── route.ts   # Test API route

By default, the SDK sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. This will give you rich debugging context.

The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.

To send less data, turn off the categories you don't need in the dataCollection option. For the full list of categories and their defaults, see the dataCollection options.

Copied

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    userInfo: false,
    // other categories
  },
});

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    userInfo: false,
    // other categories
  },
});

Important

Errors triggered from within your browser's developer tools (like the browser console) are sandboxed, so they will not trigger Sentry's error monitoring.

The example page tests all your enabled features with a single action:

Start your dev server:

Copied

npm run dev

npm run dev

Visit localhost:3000/sentry-example-page
Click "Throw Sample Error"

Errors — Open Issues

You should see "This is a test error" with a full stack trace pointing to your source code.

Tracing — Open Traces

You should see the page load trace and the button click span. Learn more about custom spans.

Session Replay — Open Replays

Watch a video-like recording of your session, including the moment the error occurred. Learn more about Session Replay configuration.

Logs — Open Logs

See structured log entries from your application. You can send logs from anywhere:

Copied

Sentry.logger.info("User action", { userId: "123" });
Sentry.logger.warn("Slow response", { duration: 5000 });
Sentry.logger.error("Operation failed", { reason: "timeout" });

Sentry.logger.info("User action", { userId: "123" });
Sentry.logger.warn("Slow response", { duration: 5000 });
Sentry.logger.error("Operation failed", { reason: "timeout" });

Learn more about Logs configuration.

Application Metrics — Open Metrics NEW

Track and analyze custom application metrics to understand trends and patterns in your app's performance and behavior over time:

Copied

Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});

Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});

Learn more about Application Metrics.

Are you having problems setting up the SDK?

If you encountered issues with our installation wizard, try setting up Sentry manually
Check Troubleshooting for common issues
Get support

You've successfully integrated Sentry into your Next.js application! Here's what to explore next:

Explore practical guides on what to monitor, log, track, and investigate after setup
Logs Integrations - Connect popular logging libraries like Pino, Winston, and Bunyan
Distributed Tracing - Trace requests across services and microservices
Agent Tracing - Monitor agents built with Vercel AI SDK, LangChain, and more
Connect GitHub + Seer - Enable AI-powered root cause analysis by connecting your GitHub repository
Configuration Options - Explore extended SDK configuration options

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support