Next.js error tracking installation

Next.js is a SSR framework with both client-side and server-side rendering. To track errors in your Next.js app, you need to install and configure the PostHog SDK for both client-side and server-side.

1
Install PostHog SDK client-side
Required
Install posthog-js using your package manager:
```
npm install --save posthog-js
```
Add your environment variables to your .env.local file and to your hosting provider (e.g. Vercel, Netlify, AWS). You can find your project API key in your project settings.
.env.local
```
NEXT_PUBLIC_POSTHOG_KEY=<ph_project_api_key>
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
```
These values need to start with NEXT_PUBLIC_ to be accessible on the client-side.
Integration
Next.js 15.3+ provides the instrumentation-client.ts|js file for a quick, lightweight setup. Add it to the root of your Next.js app (for both app and pages router) and initialize PostHog in it like this:
```
import posthog from 'posthog-js'

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
  defaults: '2025-05-24'
});
```
Using Next.js 15.2 or older?
Older versions of Next.js don't support the instrumentation-client.ts|js file. You can use the following setup instead:
If your Next.js app uses the app router, you can integrate PostHog by creating a providers file in your app folder. This is because the posthog-js library needs to be initialized on the client-side using the Next.js 'use client' directive.
// app/providers.jsx 'use client' import posthog from 'posthog-js' import { PostHogProvider as PHProvider } from 'posthog-js/react' import { useEffect } from 'react' export function PostHogProvider({ children }) { useEffect(() => { posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, { api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST, defaults: '2025-05-24', }) }, []) return ( <PHProvider client={posthog}> {children} </PHProvider> ) }
Then, import the PostHogProvider component into your app/layout file and wrap your app with it.
// app/layout.jsx import './globals.css' import { PostHogProvider } from './providers' export default function RootLayout({ children }) { return ( <html lang="en"> <body> <PostHogProvider> {children} </PostHogProvider> </body> </html> ) }
PostHog is now set up and ready to go. It will begin to autocapture events and pageviews. Files and components accessing PostHog on the client-side need the 'use client' directive.
Bootstrapping with instrumentation-client
When using instrumentation-client, the values you pass to posthog.init remain fixed for the entire session. This means bootstrapping only works if you evaluate flags before your app renders (for example, on the server).
If you need flag values after the app has rendered, you’ll want to:
- Evaluate the flag on the server and pass the value into your app, or
- Evaluate the flag in an earlier page/state, then store and re-use it when needed.
Both approaches avoid flicker and give you the same outcome as bootstrapping, as long as you use the same distinct_id across client and server.
See the bootstrapping guide for more information.
2
Capture client-side exceptions
Required
You can capture exceptions in client-side code in two ways:
1. Manual capture: Use posthog.captureException() in components that include 'use client'.
2. Autocapture: PostHog will automatically capture $exception events when errors are thrown.
Setting up exception autocapture
Note: A minimum SDK version of v1.207.8 is required, but we recommend keeping up to date with the latest version to ensure you have all of error tracking's features.
You can enable exception autocapture for the JavaScript Web SDK in the Error tracking section of your project settings.
When enabled, this automatically captures $exception events when errors are thrown by wrapping the window.onerror and window.onunhandledrejection listeners.
Manual error capture
It is also possible to manually capture exceptions using the captureException method:
JavaScript
```
posthog.captureException(error, additionalProperties)
```
Next.js uses error boundaries to handle uncaught exceptions by rendering a fallback UI instead of the crashing components.
To set one up, create a error.tsx file in any of your route directories. This triggers when there is an error rendering your component and should look like this:
error.tsx
"use client"; // Error boundaries must be Client Components import posthog from "posthog-js"; import { useEffect } from "react"; export default function Error({ error, reset, }: { error: Error & { digest?: string } reset: () => void }) { useEffect(() => { posthog.captureException(error); }, [error]); return ( ... ); }
You can also create a Global Error component in your root layout to capture unhandled exceptions in your root layout.
app/global-error.tsx
'use client' // Error boundaries must be Client Components import posthog from "posthog-js"; import NextError from "next/error"; import { useEffect } from "react"; export default function GlobalError({ error, reset, }: { error: Error & { digest?: string } reset: () => void }) { useEffect(() => { posthog.captureException(error); }, [error]); return ( // global-error must include html and body tags <html> <body> {/* `NextError` is the default Next.js error page component */} <NextError statusCode={0} /> </body> </html> ) }
Verify error tracking
Checkpoint
Confirm events are being sent to PostHog
Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

Check for exceptions in PostHog

Installing PostHog SDK for server-side

Required

Your goal in this step: Install the PostHog Node.js SDK for server-side error tracking.

Next.js enables you to both server-side render pages and add server-side functionality. To integrate PostHog into your Next.js app on the server-side, you can use the Node SDK.

First, install the posthog-node library:

npm install posthog-node --save

For the backend, we can create a lib/posthog-server.js file. In it, initialize PostHog from posthog-node as a singleton with your project API key and host from your project settings.

This looks like this:

lib/posthog-server.js

import { PostHog } from 'posthog-node'

let posthogInstance = null

export function getPostHogServer() {
  if (!posthogInstance) {
    posthogInstance = new PostHog(
      process.env.NEXT_PUBLIC_POSTHOG_KEY,
      {
        host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
        flushAt: 1,
        flushInterval: 0,
      }
    )
  }

  return posthogInstance
}

You can now use the getPostHogServer function to capture exceptions in server-side code.

JavaScript

const posthog = getPostHogServer()

try {
    throw new Error("This is a test exception for error tracking")
} catch (error) {
    posthog.captureException(error, {
        source: 'test',
        user_id: 'test-user-123',
    })
}

Verify server-side exceptions
Checkpoint
Confirm capture is working server-side
You should also see events and exceptions in PostHog coming from your server-side code in the activity feed.
Check for server events in PostHog

Capturing server-side exceptions

Required

Your goal in this step: Capture your first server-side exception event.

To capture errors that occur in your server-side code, you can set up a instrumentation.ts file at the root of your project. This provides a onRequestError hook that you can use to capture errors.

Importantly, you need to:

Set up a posthog-node client in your server-side code. See our doc on setting up Next.js server-side analytics for more.
Check the request is running in the nodejs runtime to ensure PostHog works. You can call posthog.debug() to get verbose logging.
Get the distinct_id from the cookie to connect the error to a specific user.

This looks like this:

JavaScript

// instrumentation.js
export function register() {
  // No-op for initialization
}

export const onRequestError = async (err, request, context) => {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { getPostHogServer } = require('./lib/posthog-server')
    const posthog = await getPostHogServer()
    let distinctId = null
    if (request.headers.cookie) {
      const cookieString = request.headers.cookie
      const postHogCookieMatch = cookieString.match(/ph_phc_.*?_posthog=([^;]+)/)

      if (postHogCookieMatch && postHogCookieMatch[1]) {
        try {
          const decodedCookie = decodeURIComponent(postHogCookieMatch[1])
          const postHogData = JSON.parse(decodedCookie)
          distinctId = postHogData.distinct_id
        } catch (e) {
          console.error('Error parsing PostHog cookie:', e)
        }
      }
    }

    await posthog.captureException(err, distinctId || undefined)
  }
}

You can find a full example of both this and client-side error tracking in our Next.js error monitoring tutorial.

6
Upload source maps
Required
Great, you're capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.
Let's continue to the next section.
Upload source maps for Next.js

Install PostHog SDK client-side

Integration

Capture client-side exceptions

Setting up exception autocapture

Manual error capture

Verify error tracking

Installing PostHog SDK for server-side

Verify server-side exceptions

Capturing server-side exceptions

Upload source maps

Questions? Ask Max AI.

Community questions

Was this page useful?

Python error tracking installation

Edwin Lim

Vincent Ge