Next.js Error Tracking: The Complete Guide

Error Tracking in Next.js Is Different

Next.js blurs the line between frontend and backend. With Server Components, API routes, middleware, and client components all in one project, errors can happen in multiple runtimes. Your error tracking setup needs to handle all of them.

This guide covers setting up comprehensive error tracking for Next.js 14+ with the App Router.

The Challenge: Multiple Runtimes

Next.js code runs in four different contexts:

Client-side: Browser JavaScript (client components)
Server-side (Node.js): Server Components, API routes
Edge runtime: Middleware, Edge API routes
Build time: Static generation, ISR

Each context needs different error handling.

Setting Up Bugsly for Next.js

Install the SDK

npm install @bugsly/nextjs

Configure the SDK

Create or update your instrumentation.ts file:

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const Bugsly = await import('@bugsly/node');
    Bugsly.init({
      dsn: process.env.NEXT_PUBLIC_BUGSLY_DSN,
      environment: process.env.NODE_ENV,
    });
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    const Bugsly = await import('@bugsly/edge');
    Bugsly.init({
      dsn: process.env.NEXT_PUBLIC_BUGSLY_DSN,
    });
  }
}

Client-Side Setup

Wrap your root layout with the error tracking provider:

// app/layout.tsx
import { BugslyProvider } from '@bugsly/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <BugslyProvider dsn={process.env.NEXT_PUBLIC_BUGSLY_DSN}>
          {children}
        </BugslyProvider>
      </body>
    </html>
  );
}

Handling Server Component Errors

Server Components run on the server and stream HTML to the client. Errors in Server Components need special handling because they do not trigger client-side error boundaries.

Use Next.js's error.tsx convention:

// app/error.tsx
'use client';

import { useEffect } from 'react';
import * as Bugsly from '@bugsly/browser';

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

  return (
    <div>
      <h2>Something went wrong</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

API Route Error Tracking

For API routes, wrap your handlers:

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import * as Bugsly from '@bugsly/node';

export async function GET(request: NextRequest) {
  try {
    const users = await db.users.findMany();
    return NextResponse.json(users);
  } catch (error) {
    Bugsly.captureException(error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Source Maps for Production

Add the Bugsly plugin to your Next.js config for automatic source map uploads:

// next.config.js
const { withBugsly } = require('@bugsly/nextjs');

module.exports = withBugsly({
  // your Next.js config
}, {
  org: 'your-org',
  project: 'your-project',
  authToken: process.env.BUGSLY_AUTH_TOKEN,
});

Common Next.js Errors to Watch For

Hydration mismatches: Server and client HTML differ
Dynamic server usage errors: Using dynamic features in static routes
Streaming errors: Failures during RSC streaming
Middleware timeouts: Edge runtime has strict execution limits

With this setup, all four runtime contexts are covered and you will catch errors regardless of where they originate in your Next.js application.

Try Bugsly Free

AI-powered error tracking that explains your bugs. Set up in 2 minutes, free forever for small projects.

Get Started Free