> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Unhandled Promise Rejection Monitoring

> GermainUX automatically captures unhandled JavaScript Promise rejections that occur while users interact with monitored web applications.

Components
[`JS Profiler`](/main/germain-ux-js-profiler)
[`RUM JS`](/main/germain-ux-rum-js)
[`RUM Extension`](/main/germain-ux-rum-extension)

Availability
2021.1 or later

Browser support
only latest Chrome, Edge and Opera

> **[Monitoring components](#monitoring-components)**
>
> Components needed for capture

> **[Continuous monitoring](#continuous-monitoring)**
>
> Capture rejections in live sessions

> **[Error categorization](#error-categorization)**
>
> Promote rejections to errors

> **[Deployment and configuration](#deployment-and-configuration)**
>
> Install and enable rejection capture

## Overview

GermainUX automatically captures unhandled JavaScript Promise rejections that occur while users interact with monitored web applications.

Each rejection is associated with the available application, page, browser, user, and session context, helping teams determine what failed, who was affected, and what the user experienced.

By default, all unhandled Promise rejections are collected as events. They are not categorized as errors unless an error-categorization rule identifies them as such.

## Monitoring components

| Component | Role |
| - | - |
| [GermainUX RUM JS](/main/germain-ux-rum-js.md) | Continuously captures unhandled Promise rejections when the monitoring script can be deployed in the application. |
| [GermainUX RUM Extension](/main/germain-ux-rum-extension.md) | Provides monitoring when RUM JS cannot be deployed directly or access to the complete browser-page context requires an extension. |
| [GermainUX JS Profiler](/main/germain-ux-js-profiler.md) | Captures deeper JavaScript execution, function timing, stack-trace, browser, and network evidence for code-level investigation. |

## What is an unhandled Promise rejection?

A Promise is rejected when an asynchronous JavaScript operation fails. The rejection becomes unhandled when the application does not process it with an appropriate rejection handler.

For example:

```javascript theme={null}
fetch("/api/order")
  .then((response) => response.json());
```

If the request or response-processing logic rejects the Promise and the application does not handle the rejection, the browser can report an unhandled Promise rejection.

Unhandled rejections may be associated with:

* Failed API calls.
* Invalid or unexpected response data.
* Errors in asynchronous application logic.
* Missing rejection handlers.
* Third-party script failures.
* Authentication or authorization failures.
* Aborted or interrupted operations.
* Application state or timing problems.

A rejected Promise that the application handles correctly is not an unhandled rejection.

![Unhandled Promise Rejections on Drill-through](https://mintcdn.com/germain-ux/aRWpCtnP62NYAs5c/images/main/unhandled-promise-rejection-monitoring/image-20230323-142044.png?fit=max\&auto=format\&n=aRWpCtnP62NYAs5c\&q=85\&s=45ffb750f99037ee67484bfcf1964329)

## Capabilities

GermainUX can:

* Detect unhandled Promise rejections affecting real users.
* Capture the available rejection reason or message.
* Associate the rejection with its application, page, browser, user, and session.
* Analyze frequency, recurrence, trends, and affected-user counts.
* Categorize selected rejections as errors.
* Correlate rejections with clicks, navigation, network requests, console errors, long tasks, and other browser activity.
* Show the rejection within the available Session Replay context.
* Use the JS Profiler to investigate the JavaScript functions and asynchronous activity associated with the failure.

## Default monitoring

| Capability | Default |
| - | - |
| Unhandled Promise Rejection Monitoring | Enabled |
| Rejections collected as events | Yes |
| Rejections automatically categorized as errors | No |
| Application-specific error categorization | Not configured |

No configuration is required to collect unhandled Promise rejections as events.

## Continuous monitoring

GermainUX RUM JS or the GermainUX RUM Extension continuously captures unhandled Promise rejections during real user sessions.

Use:

* **RUM JS** when the GermainUX monitoring script can be deployed directly in the application.
* **RUM Extension** when direct script deployment is unavailable or the application’s security architecture prevents access to the required browser context.

Continuous monitoring helps determine whether a rejection is isolated or repeatedly affects specific pages, workflows, browsers, application versions, or user populations.

## Code-level investigation with JS Profiler

When an unhandled rejection requires deeper technical analysis, the GermainUX JS Profiler can provide additional evidence, including:

* JavaScript function execution.
* Function duration.
* Errors and available stack traces.
* Network requests and resource loading.
* Browser events and user interactions.
* Long-running browser tasks.
* DOM activity.
* Application, page, workflow, and session context.

The JS Profiler complements continuous monitoring. It should generally be enabled for a controlled scope when deeper investigation is required.

## Business benefits

Unhandled Promise Rejection Monitoring helps organizations:

* Detect asynchronous failures that may not produce a visible application error.
* Identify the users, sessions, pages, and workflows affected.
* Find intermittent problems that are difficult to reproduce.
* Distinguish non-critical rejected operations from user-impacting errors.
* Prioritize failures according to frequency and actual business impact.
* Correlate asynchronous failures with API calls and user actions.

> **Show all 9**
>
> * Reduce the time required to identify the responsible front-end code or service.
> * Detect regressions introduced by application releases.
> * Validate whether a correction eliminated or reduced the rejection.

## Analytics

GermainUX can analyze unhandled Promise rejections through KPIs, measures, pivots, trends, drill-through views, and session context.

| Analysis area | Examples |
| - | - |
| Rejection | Reason, message, classification, or related error |
| Frequency | Occurrence count, recurrence, concentration, and trend |
| Impact | Affected users, sessions, pages, and workflows |
| Environment | Application, release, browser, operating system, and device |
| User context | Clicks, navigation, page activity, and Session Replay |
| Technical context | Network requests, console errors, long tasks, and resources |
| Code-level evidence | JavaScript functions, execution timing, and stack traces |

GermainUX users can create watches to receive notifications when collected rejection insights meet conditions of interest.

## Error categorization

By default, GermainUX stores unhandled Promise rejections as events rather than errors.

Use `settings.plugins.unhandledRejection.errorCategorizer` to identify the rejections that should also be categorized as errors.

The following example categorizes a rejection as an error when its reason contains the word `error`:

```javascript theme={null}
const settings = germainApm.getDefaultSettings();

settings.plugins.unhandledRejection.errorCategorizer = (reason) => {
  return reason != null &&
    String(reason).toLowerCase().includes("error");
};

germainApm.start(settings);
```

The categorizer must return:

* `true` when the rejection should be treated as an error.
* `false` when it should remain a standard event.

## Application-specific categorization

Error categorization can be based on known rejection messages or patterns:

```javascript theme={null}
const settings = germainApm.getDefaultSettings();

settings.plugins.unhandledRejection.errorCategorizer = (reason) => {
  const message = String(reason || "").toLowerCase();

  return (
    message.includes("payment failed") ||
    message.includes("permission denied") ||
    message.includes("service unavailable")
  );
};

germainApm.start(settings);
```

Use application-specific rules to separate user-impacting failures from expected or non-actionable rejected operations.

Avoid overly broad matching rules that could categorize every rejection as an error.

## Privacy and security

Promise-rejection reasons can contain URLs, application data, identifiers, or other sensitive information.

Before enabling application-specific collection or categorization:

* Review the rejection information produced by the application.
* Avoid placing passwords, tokens, secrets, payment data, or personal information in rejection messages.
* Normalize or sanitize sensitive application messages when necessary.
* Restrict access to detailed error and Session Replay evidence.
* Apply appropriate masking and retention requirements.
* Review the configuration after application or third-party library changes.

## Recommended investigation workflow

**1. Use RUM JS or the RUM Extension to identify an unhandled Promise rejection**

**2. Determine the affected users, sessions, pages, and workflows**

**3. Review the rejection reason and related user activity**

**4. Correlate it with network requests, console errors, clicks, and Session Replay**

**5. Categorize it as an error when it represents a user-impacting failure**

**6. Enable the JS Profiler for a controlled scope when code-level evidence is required**

**7. Identify the responsible JavaScript function, asynchronous operation, API, or dependency**

**8. Add the appropriate rejection handling or correct the underlying failure**

**9. Validate the correction through continuous monitoring**

## Deployment and configuration

* Review [Browser Monitoring](/main/browser-monitoring.md).
* Review the [Browser Monitoring Deployment Overview](/main/deployment-for-browser-monitoring.md).
* Deploy [GermainUX RUM JS](/main/germain-ux-rum-js.md) when the monitoring script can be added to the application.
* Deploy the [GermainUX RUM Extension](/main/germain-ux-rum-extension.md) when direct script deployment is unavailable or access to the complete browser-page context requires an extension.
* Deploy the [GermainUX JS Profiler](/main/germain-ux-js-profiler.md) for deeper JavaScript and browser diagnostics.
* Review the available [Browser Monitoring configuration](/main/configuration-for-browser-monitoring.md).

> **Show all 11**
>
> * Review [JavaScript Console and Error Monitoring](/main/javascript-console-and-error-monitoring.md).
> * Review [Network Request Monitoring](/main/network-requests-monitoring.md).
> * Review [Dead, Error and Rage Click Monitoring](/main/dead-error-and-rage-click-monitoring.md).
> * Review the [KPIs for User Monitoring and Replay](/main/user-monitoring-and-replay-kpis.md).
> * Review the available Browser Monitoring KPIs.

## Get Help

> **[Contact GermainUX Support](/main/support.md)**
>
> The Germain Team can help you set this up.

> **Can't find what you need?**
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.