Unhandled Promise Rejection Monitoring

ComponentsJS ProfilerRUM JSRUM Extension

Availability2021.1 or later

Browser supportonly latest Chrome, Edge and Opera

Monitoring components

Components needed for capture

Continuous monitoring

Capture rejections in live sessions

Error categorization

Promote rejections to errors

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	Continuously captures unhandled Promise rejections when the monitoring script can be deployed in the application.
GermainUX RUM Extension	Provides monitoring when RUM JS cannot be deployed directly or access to the complete browser-page context requires an extension.
GermainUX JS Profiler	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:

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

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:

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:

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

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

Determine the affected users, sessions, pages, and workflows

Review the rejection reason and related user activity

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

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

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

Identify the responsible JavaScript function, asynchronous operation, API, or dependency

Add the appropriate rejection handling or correct the underlying failure

Validate the correction through continuous monitoring

Deployment and configuration

Review Browser Monitoring.
Review the Browser Monitoring Deployment Overview.
Deploy GermainUX RUM JS when the monitoring script can be added to the application.
Deploy the GermainUX RUM Extension when direct script deployment is unavailable or access to the complete browser-page context requires an extension.
Deploy the GermainUX JS Profiler for deeper JavaScript and browser diagnostics.
Review the available Browser Monitoring configuration.

Show all 11

Review JavaScript Console and Error Monitoring.
Review Network Request Monitoring.
Review Dead, Error and Rage Click Monitoring.
Review the KPIs for User Monitoring and Replay.
Review the available Browser Monitoring KPIs.

Get Help

Contact GermainUX Support

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

Monitoring components

Continuous monitoring

Error categorization

Deployment and configuration

​Overview

​Monitoring components

​What is an unhandled Promise rejection?

​Capabilities

​Default monitoring

​Continuous monitoring

​Code-level investigation with JS Profiler

​Business benefits

​Analytics

​Error categorization

​Application-specific categorization

​Privacy and security

​Recommended investigation workflow

​Deployment and configuration

​Get Help

Contact GermainUX Support

Can't find what you need?

Overview

Monitoring components

What is an unhandled Promise rejection?

Capabilities

Default monitoring

Continuous monitoring

Code-level investigation with JS Profiler

Business benefits

Analytics

Error categorization

Application-specific categorization

Privacy and security

Recommended investigation workflow

Deployment and configuration

Get Help