--- title: Java agent error configuration source: https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-error-configuration --- APM's Java agent reports detailed information about errors that occur within your application. This gives you insight into problematic areas that may be affecting your application’s performance or the end user’s experience. With Java agent [versions 3.40.0 or higher](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes), there are several configuration options that let you control how errors are reported, including: - Configuring expected errors so that they won't affect error rate or Apdex - Ignoring errors - Reporting errors that are not reported automatically For more information on viewing your error data, see [Error analytics](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/introduction-error-analytics). For an overview of error data in all agents, see [Manage errors in APM](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-mark-expected). ## Common reported error examples [#examples] The Java agent reports errors in the following scenarios: | Error reporting | **Comments** | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Unhandled errors (includes stack trace) | If an unhandled error occurs within a transaction that the Java agent was tracing, the error will be reported with the full stack trace. | | HTTP status codes (no stack trace) | When a transaction in your application generates an HTTP status code, for example, `400` for a client error, it reports the error without a stack trace. The reasons for this are: - The application server has detected an error condition and explicitly set the status code. OR - The program logic detected the error condition, so there was no exception object or stack. In order to include the stack trace with these types of transactions, you must use a `noticeError(...)` API call. | | `noticeError(...)` API calls | If the Java agent makes an explicit call using the `noticeError(...)` API call, the error will be reported regardless of whether or not it occurs within a transaction. The reported information depends on the parameters used in the `noticeError(...)` API call, as described in the [Javadocs](https://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/NewRelic.html). | | Unscoped errors reporting over 100% | The Java agent can report unscoped errors, which are errors that are not tied to any transaction. Because of this, it is possible to have one transaction in a timeslice and multiple errors in the same timeslice. In this situation, New Relic would then show an error rate **over 100%**. | ## Configure error reporting [#error-configuration] > #### ⚠️ IMPORTANT > > In order to use this feature, [upgrade](https://docs.newrelic.com/docs/agents/java-agent/installation/upgrade-java-agent) to the [latest release](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes) (Java agent 3.40.0 or higher). The Java agent provides several flexible configuration options to control how errors are reported. | **Config options** | **Details** | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Configure errors via the UI. | You can ignore errors or mark them as expected via [server-side config](#server-side-config). | | Configure as expected errors via `newrelic.yml` | Errors reported by these versions of `noticeError` can be configured as [expected errors](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#expected-errors) in the `newrelic.yml`. Calls to this API will be overridden if the error is configured as [ignored](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#ignore-errors) in `newrelic.yml`. For details, see [Error configuration precedence](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#error-config-precedence). Use these `noticeError()` API calls to report errors that are not reported automatically and configure them as [expected errors](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#enable-error-collector) in `newrelic.yml`: - ``` noticeError(Throwable throwable) ``` - ``` noticeError(Throwable throwable, Map params) ``` | | Override expected errors via `newrelic.yml` | Errors reported by these versions of `noticeError` will override the `newrelic.yml` [expected error](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#expected-errors) configuration. Calls to this API will be overridden if the error is configured as [ignored](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#ignore-errors) in the yml. For details, see [Error configuration precedence](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#error-config-precedence). Use these `noticeError(...)` API calls to report errors that are not reported automatically and configure them as [expected errors](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-error-configuration#enable-error-collector) with the API (overrides yml expected error configuration): - ``` noticeError(String message, boolean expected) ``` - ``` noticeError(String message, Map params, boolean expected) ``` - ``` noticeError(Throwable throwable, boolean expected) ``` - ``` noticeError(Throwable throwable, Map params, boolean expected) ``` | | Ignore or expect errors via config file | In versions 3.40.0 or higher, you can control how errors are reported by using the [YAML-based configuration](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#Error_Collector). This allows you to ignore errors or expect errors based on HTTP status codes **or** based on a list of exception class names plus an optional error message. - **Ignoring errors** prevents the specified exception classes or codes from being reported to APM at all. - **Expecting errors** prevents the specified exception classes or codes from affecting your application's [error rate](https://docs.newrelic.com/docs/apis/rest-api-v2/application-examples-v2/application-error-rate-example-v2) and [Apdex score](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/apdex-measuring-user-satisfaction). This allows you to retain the error information for troubleshooting purposes while avoiding alerts based on error rate or Apdex score. These settings are dynamic, so running agents will notice changes to **newrelic.yml** without a JVM restart. For more information and examples, see the [Java agent config file](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file). | ## YAML-based configuration for error collection [#yml-config] YAML-based configuration for error collection allows you to entirely ignore specific errors or exempt expected errors from affecting your application’s error rate and Apdex score. You can mark errors as ignored or expected based on the following criteria: - A given range of HTTP status codes, presented as a comma-separated list or dashed range - A comma-separated list using the fully qualified name of a package/class **and** an optionally provided error message string **Enabling error collection** By default, the Java agent includes an `error_collector` section under which all [YAML-based error configuration](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#Error_Collector) options are found. Error collection can be enabled or disabled as follows: ````yml error_collector: enabled: true ``` ```` **Ignoring specific errors** Errors that are not of any particular interest can be ignored entirely. By identifying errors to ignore: - They will not be reported to APM. - They will not affect your application's error rate or Apdex score Here is an example showing the [YAML-based configuration](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#Error_Collector) options for ignoring errors: ```yml error_collector: enabled: true ignore_classes: - "com.example.ErrorClassToIgnore" ignore_messages: com.example.OtherErrorClassToIgnore: - "some error message to ignore" ignore_status_codes: 404,507-511 ``` **Preventing expected errors from affecting error rate and Apdex** Errors that are **expected** as part of an application's business logic can be prevented from affecting error rate or Apdex score yet still be reported to APM. This allows you to retain the error information in the UI for troubleshooting purposes while avoiding alerts (based on error rate and Apdex score) caused by these errors. Here is an example showing the [YAML-based configuration](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#Error_Collector) options for expected errors: ````yml error_collector: enabled: true expected_classes: - "com.example.ExpectedErrorClass" expected_messages: com.example.OtherExpectedErrorClass: - "some expected error message" expected_status_codes: 406,500-504 ``` ```` ## Error configuration precedence [#error-config-precedence] The priority for errors configuration is: 1. [Server-side configuration](#server-side-config) (overlays values onto YAML file) 2. `ignore_*` config in the YAML 3. `expected` parameter in the `noticeError(..)` API call 4. `expected_*` config in the YAML Here are examples of the results when combining various API calls and YAML configurations. **Ignore error classes (YAML overrides API)** YAML configuration: ````yml error_collector: ignore_classes: - "com.example.ErrorClass" ``` and API call: ```java noticeError(com.example.ErrorClass) ``` Result: The YAML `ignore_classes` overrides the `noticeError` API call, and the error is ignored. ```` **Report expected errors (YAML and API)** YAML configuration: ````yml error_collector: expected_classes: - "com.example.ErrorClass" ``` AND API call: ```java noticeError(com.newrelic.Exception) ``` Result: The `expected` parameter in the `noticeError` API call is true by default, and the YAML `expected_classes` configuration contains an error class. Therefore, the error is reported and marked as `expected`. ```` **Report expected errors (no YAML)** No YAML configuration AND API call: ````java noticeError(com.newrelic.Exception, expected = true) ``` Result: The error is reported and marked as expected. ```` **YAML ignore_classes overrides API expected parameter** YAML configuration: ````yaml error_collector: ignore_classes: - "com.example.ErrorClass" ``` AND API call: ```java noticeError(com.newrelic.Exception, expected = true) ``` Result: The YAML `ignore_classes`overrides the `expected` parameter in the `noticeError` API call, so the error is ignored. ```` **API expected parameter overrides YAML expected_classes** YAML configuration: ````yaml error_collector: expected_classes: - "com.example.ErrorClass" ``` AND API call: ```java noticeError(com.newrelic.Exception, expected = false) ``` Result: The `expected` parameter in the `noticeError` API call overrides `expected_classes` in the YAML. Therefore, the error is reported as normal (not marked as `expected`). ```` **Ignore overrides expected in YAML** YAML configuration: ````yaml error_collector: ignore_classes: - "com.example.ErrorClass" ``` AND Additional YAML configuration: ```yaml error_collector: expected_classes: - "com.example.ErrorClass" ``` Result: The YAML `ignore_classes/ignore_messages` overrides the YAML `expected_classes/expected_messages`, so the error is ignored. This same principle applies to `ignore_status_codes` and `expected_status_codes`. ```` ## Examine logs for error details [#logs-context] You can bring your logs and application's data together to make troubleshooting easier and faster. With [logs in context](https://docs.newrelic.com/docs/logs/logs-context/java-configure-logs-context-all/), you can see log messages related to your errors and traces directly in your app's UI. 1. From the **Errors** page, click on a trace to go to the [**Error details** page](https://docs.newrelic.com/docs/apm/apm-ui-pages/error-analytics/errors-page-find-fix-verify-problems/). 2. From the error details page, click **See logs**. 3. To view details related to an individual log message, click directly on the message. ## Configure ignored and expected errors via UI [#server-side-config] To configure [expected errors](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-or-mark-expected#expected) via the APM UI: 1. If it is not already enabled, [enable server-side configuration](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/server-side-agent-configuration#enable-ssc). 2. [Go to the server-side configuration menu](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/server-side-agent-configuration#customize-ssc) for the application with errors you want to mark as expected. 3. Under **Error collection**, for either **Ignore** or **Exclude expected errors**, enter the HTTP code or the error class for errors you want to configure. 4. Select **Save**. For information on how to view expected errors in the UI, see [View expected errors](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-or-mark-expected#expected).