Stack traces

Last updated:

|Edit this page|

Error tracking enables you to view the stack trace and code context associated with an exception. This can help understand, identify and resolve the root cause of an issue.

For languages like Python, the stack trace and code context can be gathered by the PostHog client and requires no additional processing.

Stack traces example

Symbol sets

Compiled or minified languages requires additional information to perform a process called symbolification to produce the same stack trace and code context output shown above. The additional information is known as a symbol set.

The source of a frame in the exception stack trace should point to the minified code of your application which should contain the sourceMappingUrl parameter denoting the location of the source map. These files must either be publicly accessible for PostHog to fetch or uploaded manually to symbolify the stack trace.

You can see the symbol sets fetched by PostHog and the associated frames within the error tracking settings. Any missing symbol sets will also be present along with the failure reason. From here, you can also manually upload missing symbol sets or replace existing ones.

Symbol set examples

Uploading source maps

If your source maps are not publicly hosted, you will need to upload them during your build process to see unminified code in your stack traces, you can either use the @posthog/nextjs-config package or the posthog-cli to handle this process.

We provide a helper package that will hook into the Next.js build process and upload sourcemaps for your client and server code. This process is enabled by default for production builds but you can disable it by setting enabled to false in the sourcemaps object.

1. Install package

Terminal
npm install @posthog/nextjs-config

2. Update your next config

next.config.js
import { withPostHogConfig } from "@posthog/nextjs-config";
const nextConfig = {
//...your nextjs config,
};
export default withPostHogConfig(nextConfig, {
personalApiKey: process.env.POSTHOG_API_KEY, // Personal API Key
envId: process.env.POSTHOG_ENV_ID, // Environment ID
host: process.env.NEXT_PUBLIC_POSTHOG_HOST, // (optional), defaults to https://us.posthog.com
sourcemaps: { // (optional)
enabled: true, // (optional) Enable sourcemaps generation and upload, default to true on production builds
project: "my-application", // (optional) Project name, defaults to repository name
version: "1.0.0", // (optional) Release version, defaults to current git commit
deleteAfterUpload: true, // (optional) Delete sourcemaps after upload, defaults to true
},
});

Where you should set the following environment variables:

Environment VariableDescription
POSTHOG_API_KEYPersonal API key with at least write access on error tracking
POSTHOG_ENV_IDProject ID you can find in your project settings
NEXT_PUBLIC_POSTHOG_HOSTYour PostHog instance URL. Defaults to https://us.posthog.com

That's it!

Now when you build your application with next build, your sourcemaps are uploaded to PostHog and you will be able to see the unminified code your error originated from in your dashboard. This step is disabled by default with next dev.

Questions? Ask Max AI.

It's easier than reading through 669 pages of documentation

Community questions

Was this page useful?

Next article

Searching and monitoring issues

What is an issue? Errors are captured as $exception events which means that you can create insights, filter recordings, trigger surveys, and more in the same way you can for any other type of event. Exception events are grouped into issues based on event information, such as the exception type, message, and stack trace. The data used for grouping depends on what is available. We're working on improving our grouping algorithm. If you spot two issues that you think should have been one, or one…

Read next article