Error Tracking Node

PostHog error tracking for Node.js

This skill helps you add PostHog error tracking to Node.js applications.

Reference files

• references/node.md - Node.js error tracking installation - docs
• references/fingerprints.md - Fingerprints - docs
• references/alerts.md - Send error tracking alerts - docs
• references/monitoring.md - Monitor and search issues - docs
• references/assigning-issues.md - Assign issues to teammates - docs
• references/upload-source-maps.md - Upload source maps - docs

Consult the documentation for API details and framework-specific patterns.

Key principles

• Environment variables: Always use environment variables for PostHog keys and host URLs. Never hardcode them.
• Minimal changes: Add error tracking alongside existing error handling. Don't replace or restructure existing error handling code.
• Autocapture first: Enable exception autocapture in the SDK initialization before adding manual captures.
• Source maps: Upload source maps so stack traces resolve to original source code, not minified bundles.
• Manual capture for boundaries: Use captureException() at error boundaries and catch blocks for errors that don't propagate to the global handler.

Framework guidelines

• posthog-node is the Node.js server-side SDK package name – do NOT use posthog-js on the server
• Include enableExceptionAutocapture: true in the PostHog constructor options
• Add posthog.capture() calls in route handlers for meaningful user actions – every route that creates, updates, or deletes data should track an event with contextual properties
• Add posthog.captureException(err, distinctId) in the application's error handler (e.g., Express error middleware, Fastify setErrorHandler, Koa app.on('error'))
• In long-running servers, the SDK batches events automatically – do NOT set flushAt or flushInterval unless you have a specific reason to
• For short-lived processes (scripts, CLIs, serverless), set flushAt to 1 and flushInterval to 0 to send events immediately
• Reverse proxy is NOT needed for server-side Node.js – only client-side JavaScript needs a proxy to avoid ad blockers
• Remember that source code is available in the node_modules directory
• Check package.json for type checking or build scripts to validate changes

Send error tracking alerts - Docs

To stay on top of issues, you can set up alerts. These enable you to post to Slack, Discord, Teams, or an HTTP Webhook when an issue is created or reopened.

Issue created or reopened

To alert when an issue is created or reopened, go to error tracking's configuration page and click Alerting. This shows you a list of existing alerts. Clicking New notification brings you to a page to create a new one.

!Error tracking alerting!Error tracking alerting

Choosing an option brings you to a page to configure the alert. This may require setting up the Slack integration or pasting in a webhook URL. Once done, you can test the alert by clicking Test function and then finalize by clicking Create & enable.

This will then send alerts to your chosen destination when an issue is created or reopened like this:

Issue properties and assignments

You can filter an alert based on the properties of an issue. This is useful for notifying a specific team when they have been auto assigned an issue using auto assignment rules.

!Error tracking alert assignee filtering!Error tracking alert assignee filtering

Spike alerts

PostHog can also alert you when an existing issue suddenly spikes in volume - for example, after a bad deploy. This works differently from issue-created alerts. Instead of triggering when a new issue is first seen, spike alerts fire when an issue's error rate significantly exceeds its historical baseline.

See the spike detection guide to learn how it works and how to configure it.

Other alerting options

Since error tracking works by capturing $exception events, PostHog features that trigger by events can play a role in alerts too.

Real time destinations

The first way is using real time destinations. This enables you to send events (like $exception) to other tools as soon as they are ingested.

To create a real time destination, go to the data pipelines tab in PostHog, click \+ New, and then select Destination. Choose your destination and press \+ Create.

On the destination creation screen, make sure to add an event matcher for the $exception event, filter for the properties you want, and set the trigger options.

!Real time destination!Real time destination

Check out our real time destinations docs for more information.

Trend alerts

You can also visualize your $exception events using trends. Once you create a trend insight, click the Alerts button at the top of the insight and then New alert.

Here you can set alerts for event volume value, increase, or decrease.

!Insight alert!Insight alert

This sends an email notification to the user you choose. Check out our alerts docs for more information.

Can't find your alert?

If you'd like a destination to be added that we don't yet support, let us know in-app.

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Assign issues to teammates - Docs

Error tracking enables you to assign issues to specific PostHog roles or teammates. This helps your team find relevant issues through filtering. You can also set up team-specific alerting to notify them when assigned issues are created or reopened.

Assign issues

You can manually assign issues as you triage them in the UI. This can be done both in the issue list and issue detail pages.

!Error tracking assignment UI!Error tracking assignment UI

1. In your error tracking issue list, click the unassigned selector under each issue to assign it to a role or user.

2. On the detail page of each issue, click the Assignee selector to assign it to a role or user.

Want to assign issues to a team rather than an individual teammate? You can create a role in your project settings.

!Error tracking role assignees!Error tracking role assignees

Automatic issue assignment

You can set up automatic issue assignment through a set of rules. This can be configured in the error tracking settings using auto assignment rules.

!Error tracking auto assignment rules!Error tracking auto assignment rules

Assignment conditions are evaluated against the properties of the exception event that created the issue. Because assignment rules are evaluated during ingestion, the stack trace (if present) will be unminified, which enables filtering on exception properties such as function name and source file.

Issues can be automatically assigned to a role or user by configuring a set of filters. These filters can be configured to match any or all of the criteria.

You can configure automatic assignment to filter on any event property in PostHog. When there are multiple values for a property, the filters return true if it matches any of the values. For example, if you have multiple exception_functions values, the filters returns true if it matches any of the functions.

Here are some common properties you can filter on:

You can also set custom properties on the error tracking event to filter on. For example, setting a custom params_received property to provide more context or debug information.

Order of issue assignment rules

Issue assignment filters are evaluated in the order they are configured. They can also be reordered once created. The first filter that matches is used to assign the issue. This means you should configure the most specific filters first, and then the more general filters later.

Disabled assignment rules

Assignment rules can become disabled if an error occurs during ingestion. When a rule is disabled, a banner displays the original error message. To re-enable the rule, edit it to fix the problem and save your changes. If the issue persists, reach out to support.

Alerting based on assignment

A common use case for automatic issue assignment is to alert assignees of new issues. Once the issues are automatically assigned, you can set up alerts to notify the assignee. See the alerts guide for more information.

Create external issues

You can also create issues in external tracking systems like GitHub Issues, Linear, GitLab, or Jira.

First, set up an integration with your tracking system. Then, from an issue's details page, under External references, click Create issue.

!Error tracking create issue in external tracking system!Error tracking create issue in external tracking system

The new issue will have a partial stack trace and a link to the issue in PostHog.

If you use another issue tracking system and would like to request it, let us know in-app.

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Fingerprints - Docs

Every captured exception is assigned a fingerprint. This fingerprint is used to group similar exceptions into issues. This page covers how fingerprints are generated, how they're used, and how you can override them when capturing exceptions.

Fingerprint and issue grouping

Every exception has a fingerprint, whether generated or defined by the user. Each fingerprint links to exactly one issue. Exceptions that share the same fingerprint define an issue.

Multiple different fingerprints can point to the same issue (a many-to-one relationship) if you merge issues.

How are fingerprints generated?

Fingerprints are built iteratively using components of the exception event. The flowchart below shows how fingerprints are generated.

flowchart LR A\[Add exception type to fingerprint\] --> B{Stack trace<br/>available?} B -->|No| C\[Add error message to fingerprint\] C --> D\[Final fingerprint\] B -->|Yes| E{In-app frames<br/>exist?} E -->|No| F\[Add first frame to fingerprint\] E -->|Yes| G\[Add in-app frame to fingerprint<br/>Priority: resolved > unresolved\] F --> D G --> D

The flowchart in text

Fingerprints are generated by considering the following in combination:

1. The exception type 2. If there's no resolved stack trace, add the error message to the fingerprint 3. If there are stack traces but no in-app frames (frames from your code, not a dependency), use the first frame of the stack trace 4. If there are stack traces, in-app frames, and source maps available, use the resolved in-app stack frames 5. If there are stack traces, in-app frames, and source maps not available, use the first in-app stack frame

In some languages, like Python, one error can trigger another, creating a chain of linked exceptions. PostHog records the entire chain in the event and generates a single fingerprint for it.

Ensuring accurate fingerprints

Resolved stack traces are critical for accurate fingerprinting. Without accurate stack traces, PostHog cannot group exceptions consistently. If you have not uploaded source maps, follow the source map guide to do so.

This also means that if the exception type or message changes from one version to the next, the fingerprint will change.

When are generated fingerprints used?

Fingerprints are used to group similar exceptions into issues automatically. Automatic issue grouping is only done when:

• No issue grouping rules are applied
• No issue merging has been configured
• No custom fingerprint is set during capture

You can find details about how issue grouping works in the issues and exceptions guide.

Customizing fingerprints

Fingerprints can be manually set during exception capture. This is a very useful way to group exceptions that are not related to each other. You can find examples of how to do this in the custom issue grouping section.

You can also learn more about grouping issues using rules in the grouping issues guide.

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Monitor and search issues - Docs

This guide covers how to find the most relevant, urgent, and impactful issues in your error tracking using the issues page.

Monitoring issues

When you're monitoring issues in your project, there are generally two common workflows:

• You're exploring issues to identify impactful and problematic areas. You should use sorting features.
• You're looking for issues assigned to you to resolve them. You should filter by the Assigned to property.

Sorting issues

Issues can be sorted by the following properties:

Sorting by last seen and occurrences are great ways to get a general sense of issues in your project. Sorting by users and sessions is great to find the most impactful issues if you're using other filters to narrow down your results.

Monitoring issues assigned to you

You can filter issues by the Assigned to property to find issues assigned to you. This is especially useful if you configure automatic issue assignment and configure alerts to notify you when new issues are created.

Finding specific issues

You can use the search bar at the top of the issue page to filter issues based on the properties of the exceptions in that issue.

Search results are matched based on properties of exception events grouped into the issues. For example, if you search for "TypeError", we show you all issues where any exception grouped into the issue has a type of "TypeError".

Unrelated results

You may see seemingly unrelated issues in your search results because your search term matches an exception in the issue group. For example, you may see an issues named RefreshError when searching "schema", because a get_schema method appears on the exception stack traces.

Filtering modes

The search bar provides two modes of filtering:

1\. Exact property filtering

This operates like property filters elsewhere in PostHog, enabling you to add terms like where 'http_referer' is set or where 'library' equals 'web'. You add a property filter by clicking the property name shown here:

!Adding a property to the property filter!Adding a property to the property filter

Added property filters look like this:

!Search bar with property filter!Search bar with property filter

The results of both of these filter types (property filters and freeform search) are combined with AND logic, such that only exceptions that match all filters are included in the search results.

2\. Freeform text search

This does text matching for a subset of the error tracking specific properties of the exception event. It splits the text you give it into tokens. The search matches an exception if each of the tokens in your search term appear in one of the following:

• The exception type
• The exception message
• The function names in the exception stack trace (if known)
• The file paths in the exception stack trace (if known)

For example, imagine you have an exception that looks like this:

PostHog AI

TypeError: Cannot read property 'name' of undefined
    at Object.<anonymous> (/path/to/myfile.js:123:45)
    at Module._compile (module.js:653:30)
    at Object.Module._extensions..js (module.js:664:10)
    at Module.load (module.js:566:32)
    at tryModuleLoad (module.js:506:12)
    at Function.Module._load (module.js:498:3)
    at Function.Module.runMain (module.js:694:10)
    at startup (bootstrap_node.js:204:16)
    at bootstrap_node.js:625:3

If you search for the term TypeError myfile.js, the exception matches this search, as it contains TypeError (as the exception type) and myfile.js (as a file path in the stack trace).

If you search for TypeError myfile.js abc, the exception would not match, as the token abc does not appear anywhere in freeform search properties.

If you want to search for longer exact strings, e.g. a particular exception message, you can group tokens into a single term using quotes, e.g. "Cannot read property 'name' of undefined" myfile.js would match, and "Cannot read property of myfile.js" would not.

Note, perhaps unintuitively, Cannot read property of myfile.js would match, because the tokens are ungrouped, and all of them appear somewhere in the exception search properties.

Searching chained exceptions

Exception events can have more than one exception in them, due to language features like exception chaining. For freeform search, we put the types, messages, functions and file paths of all exceptions into one list, and match if the token appears in any of them.

For example, if you had a chained exception with the messages MyCustomError: Failed to load user and Cannot read property 'age' of undefined, searching for cannot read property would match the exception, because it matches one of the exception messages (property appears in the "root" one).

Issue details

When you click on an issue, you'll see the details page of the issue.

This page shows you the following:

• The stack trace, properties, and sessions related to the currently selected exception.
• Name, description, status, assignee, and external tracking links for the issue.
• A filterable list of all exceptions in the issue. Selecting an exception will show you the stack trace, properties, and sessions related to that exception at the top of the page.

!An issue, with an unfiltered exception list!An issue, with an unfiltered exception list

Filtering exception occurrences within an issue

Once you've found and opened the issue you want to investigate, you can use the same search interface to filter the exception list for a particular instance of the issue. This is particularly useful in cases where some exceptions in the issue have information others don't and you want to use that information for debugging.

For example, you can add a property filter on http_referer that shows all exceptions where the http_referer is set:

!An issue, with a filtered exception list!An issue, with a filtered exception list

Alerts

If you have a set of filters that you use often, you can create alerts for them. This way you can be notified when new issues match your filters. Learn more about alerts.

Improving search performance

We try to return results to you within a second, but sometimes if you're querying over large amounts of data, it may take longer. The following can improve the search performance:

• Limit the time range you're searching over: 7 days is usually enough to get a sense for the trends of an issue over time.

• Use freeform search rather than property filters: Our freeform searches are generally faster than property filters, as the total amount of data processed is smaller.

If you find your queries timing out or taking more than 30 seconds, please let us know in-app! We're always looking for benchmarks to improve against.

Suppressing issues

If you find issues that are not useful to you, you can suppress them by changing the status to Suppressed. We recommend that you also implement client-side suppression to not capture these exceptions in the first place, for cost and performance reasons.

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Node.js error tracking installation - Docs

1. 1

Install the package

Required

Install the PostHog Node.js library using your package manager:

PostHog AI

npm

    npm install posthog-node

yarn

    yarn add posthog-node

pnpm

    pnpm add posthog-node

2. 2

Initialize PostHog

Required

Initialize the PostHog client with your project token:

Node.js

PostHog AI

    import { PostHog } from 'posthog-node'
    const client = new PostHog(
        '<ph_project_token>',
        {
            host: 'https://us.i.posthog.com'
        }
    )

3. 3

Send an event

Recommended

Once installed, you can manually send events to test your integration:

Node.js

PostHog AI

    client.capture({
        distinctId: 'distinct_id_of_the_user',
        event: 'event_name',
        properties: {
            property1: 'value',
            property2: 'value',
        },
    })

4. 4

Configure exception autocapture

Recommended

You can enable exception autocapture when initializing the PostHog client to automatically capture uncaught exceptions and unhandled rejections in your Node app.

Node.js

PostHog AI

    import { PostHog } from 'posthog-node'
    const client = new PostHog(
        '<ph_project_token>',
        { host: 'https://us.i.posthog.com', enableExceptionAutocapture: true }
    )

If you are using the Express framework, you will need to import and call setupExpressErrorHandler with your PostHog client and Express app. This is because Express handles uncaught exceptions internally meaning exception autocapture will not work by default.

server.ts

PostHog AI

    import express from 'express'
    import { PostHog, setupExpressErrorHandler } from 'posthog-node'
    const app = express()
    const posthog = new PostHog(POSTHOG_PROJECT_TOKEN)
    setupExpressErrorHandler(posthog, app)

Note: Error tracking requires access the file system to process stack traces. Some providers, like Cloudflare Workers, do not support Node.js runtime APIs by default and need to be included as per their documentation.

5. 5

Manually capture exceptions

Optional

If you need to manually capture exceptions, you can do so by calling the captureException method:

Node.js

PostHog AI

    posthog.captureException(e, 'user_distinct_id', additionalProperties)

This is helpful if you've built your own error handling logic or want to capture exceptions normally handled by the framework.

6. ## Verify error tracking

Recommended

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.

!Activity feed with events!Activity feed with events

Check for exceptions in PostHog

7. 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

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Upload source maps - Docs

If you serve compiled or minified code, PostHog requires source maps to generate accurate stack traces.

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.

Choose your platform to view specific instructions.

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• CLI

• 

Community questions

Ask a question

Was this page useful?

HelpfulCould be better