---
title: Handled exceptions: Analyze trends, prevent crashes, investigate occurrences
source: https://docs.newrelic.com/docs/mobile-monitoring/mobile-monitoring-ui/crashes/handled-exceptions-analyze-trends-prevent-crashes
---

Our handled exceptions monitoring feature helps you identify significant factors contributing to poor mobile application experience, and use filterable data to find a resolution more quickly. You can also use the [handled exceptions API](#hex-api) to customize the data you send, and use NRQL to query and share the data.

![Mobile Handled Exceptions](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exceptions-summary.webp "Mobile Handled Exceptions")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions:** As you explore the wealth of data in the charts and table, use groups and filters to discover patterns that help you determine the root cause of mobile app exceptions.

## Features

Handling exceptions as they occur can help improve your mobile app users' experience, but it's not enough to catch exceptions. You also need to know how to prevent them. Our Handled exceptions feature helps you answer these kinds of questions:

-   How many different types of handled exceptions are occurring? A high occurrence rate may indicate you need to make changes to the backend systems.
-   Why does the user's app usage result in a try/catch? What is the context for the exceptions?
-   When can a test environment's responses to handled exceptions indicate additional, more serious problems?
-   What would have caused a crash if the exception had not been caught in production? What else (in the code or backend API) is still affecting the users' experience?

By using handled exceptions, you can identify and resolve these kinds of issues more quickly.

## Requirements

To view handled exception data, your app needs to meet these requirements:

-   **Android:** [Android agent version 5.15.0 or higher](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/android-release-notes)
-   **iOS:** [iOS agent version 5.15.0 or higher](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/ios-release-notes)

## Exception percentage charts [#percentage-charts]

Start with the **Users affected** and **Sessions affected** percentage charts to see if there are any unexpected spikes, dips, or patterns with exceptions in general. If the **Users affected** chart is empty, that means there were no user sessions during the selected time period.

Use this to answer questions like:

-   Are there any spikes near a recent version release?
-   Is there a time period when the percentage of users has been affected significantly by the exception?
-   Are there uneventful periods?

To examine data in greater detail: Below any chart, select [**Expand chart**](#top5-image).

**Exception percentage charts example**

![Mobile Handled Exceptions: Percentage charts](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exception-percentages.webp "Mobile Handled Exceptions: Percentage charts")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions:** The percentage charts help you quickly see any unexpected spikes, dips, or patterns with exceptions in general.

## Groups and filters [#groups-filters]

Use the groups and filters to examine attributes for crashes, devices, locations, or other custom attributes in more detail. You can select a group, then filter to specific data. Use this to do things like:

-   Group the list by exception location (default), cause, app build or version, devices, connections, or other custom attributes. This lets you discover patterns in your exceptions to determine the root cause.
-   Use the [time picker](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/manage-your-dashboard/#dash-time-picker) to adjust the currently selected time period.
-   Filter by a specific **Version** or by one or more attribute **Filter**, such as `appVersion`, `exceptionLocationMethod`, `lastInteraction`, or any of the [longer list](https://docs.newrelic.com/docs/insights/insights-data-sources/default-data/mobile-events-attributes) of standard and custom attributes.

The currently selected filters appear at the top of the UI page. You can close them, add other filters, or select other groups and filters.

**Groups and filters example**

![Mobile Handled Exceptions: Groups and filters](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exception-groups.webp "Mobile Handled Exceptions: Groups and filters")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions:** Group the data by attributes that matter to the most to you, then select one or more filters to help pinpoint specific causes behind the exceptions.

## Top exception locations [#top5-exceptions]

Use the **Top exception locations** table to find or sort patterns in the type of exception you selected from the [groups and filters](#groups-filters). This includes:

-   Recurring locations in the stack trace
-   Mobile app version
-   Number of occurrences
-   Number of users affected during the [selected time period](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/manage-your-dashboard/#dash-time-picker)

For example, you can group by `Exception Message`, filter to `timeout` message, then select individual timeout locations from the table to review the stack trace thread and details about each occurrence.

-   To filter or group by other attributes, use the table's search window, or select any of the available filters. For example, filter by type of occurrence, device, a specific location, or any custom attributes.
-   To look for other historical patterns, change the selected time period.

**Top exception locations example**

![Mobile Handled Exceptions: Top locations](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exception-locations.webp "Mobile Handled Exceptions: Top locations")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions:** This example shows the **Expand chart** button and links to the query builder, where you can query, create dashboards, and share the handled exceptions data.

## Query builder links [#insights]

**Handled exceptions** charts use default attributes for mobile events (including [`MobileHandledException`](https://docs.newrelic.com/docs/insights/insights-data-sources/default-data/mobile-events-attributes#mobilehandledexception-attributes)), along with any custom attributes you have added to this event type. When you mouse over the charts, [direct links](#top5-image) appear below them. These links to the query builder allow you to analyze your mobile app data even deeper.

-   **View query** link: View the [NRQL query](https://docs.newrelic.com/docs/insights/new-relic-insights/using-new-relic-query-language/using-nrql) used to calculate the chart data.
-   **View in query builder** link: [View the chart](https://docs.newrelic.com/docs/insights/new-relic-insights/using-insights-interface/query-page-creating-editing-nrql-queries), and share it with others.

## Exception locations table [#locations-table]

The **Exception locations** table supplements the charts. It lists where the top five handled exceptions appear in their stack trace thread, and links them to relevant details. Each row helps you find answers to questions such as:

-   How many of this exception occurred within the selected [time period](#time-period)?
-   Does a specific app version have a higher (or lower) number of users affected?
-   Which exception has the fewest number of occurrences?

You can change the sort order or filter options to focus on just the types of exceptions that matter the most to you and your teams. To view additional [thread details for each occurrence](https://docs.newrelic.com/docs/mobile-monitoring/mobile-monitoring-ui/crashes/handled-exceptions-occurrences) of the exception, select a record from the **Top exceptions location** table.

**Exception locations table example**

![Mobile Handled Exceptions: Locations table](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exception-location-example.webp "Mobile Handled Exceptions: Locations table")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions > (click on an exception):** To continue to the handled exception's **Occurrences** page, select any row on the table.

## Handled exception occurrence details [#hex-occurrences]

To view details for each occurrence of a handled exception:

1.  Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions**.
2.  From the **Top exception locations** table, select a handled exception on any row.

The **Occurrences** page shows details about the selected exception, including breakdown data by device type or operating system, number of users affected, total occurrences for the selected time period, attributes, and more.

![Mobile Handled Exceptions: Occurrences](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exception-occurrences.webp "Mobile Handled Exceptions: Occurrences")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions > (select an exception) > Occurrences:** Use the thread details to further examine patterns in the stack trace for a handled exception.

| **If you want to...**                  | **Do this**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Find general patterns                  | From the **Occurrences** page: - Review the selected occurrence's **Summary** information. - Compare the **Occurrence by version** and **Breakdown of handled exception type** charts. - On the **Breakdown of handled exception type** chart, toggle between `Device type` and `OS version`. - Use the [time picker](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/manage-your-dashboard/#dash-time-picker) to adjust the currently selected time period. - To look for other patterns, select **Back to handled exceptions**. |
| Find more specific patterns            | Do any of the following: - From the top of the page, select a specific **Version**, or select one or more **Filter**. - Examine the data in the thread. - From the **Stack trace** details, scroll through the number of occurrences. - Use the [time picker](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/manage-your-dashboard/#dash-time-picker) to adjust the currently selected time period.                                                                                                                              |
| Find patterns from attributes          | Review the lists of [`MobileHandledException`attributes](https://docs.newrelic.com/docs/insights/insights-data-sources/default-data/mobile-events-attributes#mobilehandledexception-attributes) related to the occurrence, including: - Handled exceptions - Device - Connection - Location - Other, such as [custom attributes](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-events/insert-custom-events-attributes-mobile-data) you created                                                                                          |
| Query or visualize the occurrence data | Use New Relic to [query the data](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/using-nrql/query-page-create-edit-nrql-queries) or to [create dashboards](https://docs.newrelic.com/docs/insights/use-insights-ui/manage-dashboards/create-edit-copy-insights-dashboards) that you can view or share.                                                                                                                                                                                                                                  |

### Event trails for an occurrence [#event-trail]

The **Event trail** chart allows you to see timestamped events leading up to a handled exception.

![event trail chart for handled exceptions](https://docs.newrelic.com/images/mobile_screenshot-full_event-trail-handled-exceptions.webp "event trail chart for handled exceptions")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Exceptions > Handled exceptions > (click an exception) > (scroll down to Event trail chart):**  View the event trail for events leading up to a handled exception.

## Unsymbolicated stack traces [#unsymbolicated]

New Relic does not store unsymbolicated stack traces for handled exceptions. This is different than the [crash event trail](https://docs.newrelic.com/docs/mobile-monitoring/mobile-monitoring-ui/crashes/mobile-crash-event-trail). You can [upload a dSYM](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/install-configure/upload-dsyms-bitcode-apps) later as needed, as new handled exceptions will become symbolicated.

## Handled exceptions API [#hex-api]

Our **Handled exceptions** feature automatically includes default attributes that you can use to explore your handled exceptions data in the query builder and get specific details:

-   Use the [`recordHandledExceptions()` method](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-handled-exceptions/).
-   [Query](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/using-nrql/query-page-create-edit-nrql-queries) the [`MobileHandledException`](https://docs.newrelic.com/docs/insights/insights-data-sources/default-data/mobile-events-attributes#mobilehandledexception-attributes) event type. For more information, see the [NRQL examples](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/nrql-query-examples/insights-query-examples-new-relic-mobile#mobilehandledexception-examples) for mobile monitoring.

## Create custom attributes and events

You can also [custom attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/maintenance/add-custom-data-new-relic-mobile/#custom-attributes) and [custom events](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/maintenance/add-custom-data-new-relic-mobile). Once you create them, select and query the attributes on the **Handled exceptions** page.