Unhandled Promise Rejection Monitoring

Unhandled Promise Rejection Monitoring

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

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

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

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.

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

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

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

ℹ️ Get Help

The Germain Team can help you set this up. Contact GermainUX Support.