---
title: newrelic_notice_error (PHP agent API)
source: https://docs.newrelic.com/docs/apm/agents/php-agent/php-agent-api/newrelic_notice_error
---

## Syntax

```php
newrelic_notice_error(string $message)
newrelic_notice_error(Throwable|Exception $e)
newrelic_notice_error(string $errstr, Throwable|Exception $e)
newrelic_notice_error(int $errno, string $errstr, string $errfile, int $errline)  (PHP 8+)
newrelic_notice_error(int $errno, string $errstr, string $errfile, int $errline, string $errcontext) (PHP 7)
```

Use these calls to collect errors that the PHP agent does not collect automatically and to set the callback for your own error and exception handler.

## Requirements

Agent version 2.6 or higher.

> #### ⚠️ CAUTION
>
> If you include an exception (`$e`), there are differences depending on the PHP version you are using:

-   **PHP version 5 or lower**: You must pass a valid PHP **Exception** class.
-   **PHP version 7 or higher**: You must pass a valid PHP **Throwable** interface.

## Description

The PHP agent handles PHP errors and exceptions [automatically for supported frameworks](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-mark-expected).

If you want to collect errors that are not handled automatically so that you can [query](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/using-nrql/introduction-nrql) for those errors in [New Relic](https://docs.newrelic.com/docs/insights/use-insights-ui/getting-started/introduction-new-relic-insights) and view [error traces](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/error-analytics-explore-events-behind-errors#traces-table), you can use `newrelic_notice_error`.

If you want to use your own error and exception handlers, you can set `newrelic_notice_error` as the callback.

### Collect errors that are not handled automatically [#own-exception-handler]

To collect errors that the PHP agent does not handle automatically, such as non-PHP errors, [add this call to the function that you want to report on](#non-php-exceptions):

```php
newrelic_notice_error(Throwable|Exception $e)
```

> #### ⚠️ IMPORTANT
>
> When there are multiple calls to this function in a single transaction, the PHP agent retains the exception from the last call only.

### Set the callback for your own error and exception handler [#set-callback]

To use your own handler, use these calls to make sure that the PHP agent notices the errors and exceptions from within your handler.

**`set_exception_handler()`**

To [provide `newrelic_notice_error` as the callback](#custom-exception-handler) for [`set_exception_handler()`](https://secure.php.net/manual/en/function.set-exception-handler.php), use the following:

````php
newrelic_notice_error(Throwable|Exception $e)
```

````

**`set_error_handler()`**

To [provide `newrelic_notice_error` as the callback](#custom-error-handler-5) for [`set_error_handler()`](https://secure.php.net/set_error_handler), use the following:

PHP 7.x

````php
newrelic_notice_error(int $errno, string $errstr, string $errfile, int $errline, string $errcontext)
```

PHP 8.x

```php
newrelic_notice_error(int $errno, string $errstr, string $errfile, int $errline)
```

````

## Parameters

This function can handle a variable number of parameters. You can pass-in 1, 4 or 5 parameters, depending on your use case.

```php
newrelic_notice_error(string $message)
```

| Parameter           | Description                                                                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$message` _string_ | Required. Provide an error message that will be meaningful to you when it displays in [error traces](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/error-analytics-explore-events-behind-errors#traces-table). |

```php
newrelic_notice_error(Throwable|Exception $e)
```

| Parameter        | Description                                                                                                                                                                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$e` _exception_ | Required. Defaults to `null`. - The agent uses [`Exception` or `Throwable`](#version-difference) to capture the stack frame and set the error class to the exception class name. - If `null` or omitted, the agent reports an "exception" in the same format created by `Exception::__toString`. |

PHP 7.3

```php
newrelic_notice_error(int $errno, string $errstr, string $errfile, int $errline, string $errcontext)
```

PHP 8.x

```php
newrelic_notice_error(int $errno, string $errstr, string $errfile, int $errline)
```

| Parameter              | Description                                                                                                                                                                                                                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$errno` _integer_     | Required. The [predefined level of the error](http://php.net/manual/en/errorfunc.constants.php), expressed as an integer.                                                                                                                                                                                        |
| `$errstr` _string_     | Required. Provide an error message that will be meaningful to you when it displays in [error traces](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/error-analytics-explore-events-behind-errors#traces-table).  This can be used to include additional information you would like to see. |
| `$errfile` _string_    | Optional. The name of the file that the error occurred in. NOTE: This parameter is ignored by the agent - the agent will provide a stack trace with this information.                                                                                                                                            |
| `$errline` _integer_   | Optional. The line number where the error occurred. NOTE: This parameter is ignored by the agent - the agent will provide a stack trace with this information.                                                                                                                                                   |
| `$errcontext` _string_ | Optional. An array that points to the symbol table that was active when the error occurred. NOTE: The agent ignores this parameter - and it is not supported with PHP 8+.                                                                                                                                        |

## Return values

Returns `null` regardless of result.

## Examples

### Collect errors that are not handled automatically [#non-php-exceptions]

Track errors that aren't reported automatically or that aren't PHP errors. In this example, an error is sent to the PHP agent if an unknown user accesses your app.

```php
try {
    // Add your code that may throw an error here.
} catch (UserNotFoundException $e) {
    newrelic_notice_error($e);
    // Handle normally.
}
```

### Report exceptions from your own exception handler [#custom-exception-handler]

Make the PHP agent notice exceptions from within your own exception handler.

```php
function example_exception_handler($ex) {
    if (extension_loaded('newrelic')) {
        newrelic_notice_error($ex);
    }
    //Add your code here.
}
```

### Report errors from your own error handler (PHP version 5.6 or higher) [#custom-error-handler-5]

**PHP version 5.6 or higher**: Make the PHP agent notice errors from within your own error handler.

```php
function example_error_handler($errno, $errstr, $errfile = null, $errline = null, $errcontext = null) {
    if (extension_loaded('newrelic')) {
        newrelic_notice_error(...func_get_args());
    }
    //Add your code here.
}
```

### Report errors from your own error handler (PHP version 5.5 or lower) [#custom-error-handler-7]

**PHP version 5.5 or lower**: Make the PHP agent notice errors from within your own error handler.

```php
function example_error_handler($errno, $errstr, $errfile = null, $errline = null, $errcontext = null) {
    if (extension_loaded('newrelic')) {
        call_user_func_array('newrelic_notice_error', func_get_args());
    }
    //Add your code here.
}
```