# CFERROR

Provides the ability to display customized HTML pages when errors occur. This allows you to maintain a consistent look and feel within your application even when errors occur.

### Syntax

    <CFERROR
        TYPE="Request" or "Validation" or "Monitor" or "Exception"
        TEMPLATE="template_path"
        MAILTO="email_address"
        EXCEPTION="exception_type">

#### TYPE

Required. The type of error that this custom error page is designed to handle:

- Specify Exception to handle exceptions.
- Specify Validation to handle data input validation errors that occur when submitting a form. A validation error handler is only useful if placed inside the `Application.cfm` file.
- Specify Monitor to set up an exception monitor.
- Specify Request to handle errors that occur during the processing of a page. Request is the default.

See the table under CFERROR Error Variables for information about the variables and other constructs available from the templates used to handle each type of error.

#### TEMPLATE

Required. The relative path to the custom error handling page. The following table describes the template to use for each type of error.

Types and Their Corresponding Custom Error Pages
Type | Custom Error Page
--- | ---
    Exception
| An exception-handling template that is dynamically invoked by the CFML language processor when it detects an unhandled exception condition. Exception-handling templates may be specified as part of an application, via the <CFERROR TYPE="Exception"> tag, or may be set via the ColdFusion Administrator. An exception-handling template can use the full range of CFML tags, making it significantly more powerful than <CFERROR TYPE="Request">. This template also has access to the error variables in the table under CFERROR Error Variables.

Types and Their Corresponding Custom Error Pages (Continued)
Type | Custom Error Page
--- | ---
    Request
| This template can include only the error variables described in the table under CFERROR Error Variables and cannot include CFML tags. It is useful as a backup error handler for sites with high user interface requirements.
    Validation
| A validation error handler. It handles data input validation errors that occur when submitting a form. It is useful only if placed inside the `Application.cfm` file.
    Monitor
| An exception-monitoring template is dynamically invoked by the CFML language processor when it first detects an exception condition, before it searches for <CFTRY>/<CFCATCH> or <CFERROR> handlers for the exception. Exception-monitoring templates are useful for monitoring and debugging exception handling within complex applications.

#### MAILTO

Optional. The email address of the administrator who should be notified of the error. This value is available to your custom error page using the MailTo property of the error object, such as #Error.MailTo#.

#### EXCEPTION

Required if the type is specified as Exception or Monitor. The type of exception.

### Usage

The CFERROR tag is normally used to customize the error messages for all the pages in an application. As a result, you generally embed it in the `Application.cfm` file. For more information about the `Application.cfm` file, refer to Developing Web Applications with ColdFusion.

To help ensure that error pages display successfully, pages you specify with CFERROR should not be encoded with the `cfencode` utility.

## CFERROR Error Variables

The exception-handling template specified in the TEMPLATE attribute of the CFERROR tag may contain one or more error variables, which will be substituted by ColdFusion when an error is displayed.

### Error Variables for Request, Exception, and Monitor Types

The following error variables are available when CFERROR specifies TYPE="Request", TYPE="Exception" or TYPE="Monitor":

Variables for Request, Exception, and Monitor Types
Error Variable | Description
--- | ---
    Error.Diagnostics
| Detailed error diagnostics from ColdFusion Server.
    Error.MailTo
| Email address of administrator who should be notified (corresponds to the value set in the MAILTO attribute of CFERROR).
    Error.DateTime
| Date and time when the error occurred.
    Error.Browser
| Browser that was running when the error occurred.
    Error.GeneratedContent
| The failed request's generated content .
    Error.RemoteAddress
| IP address of the remote client.
    Error.HTTPReferer
| Page from which the client accessed the link to the page where the error occurred.
    Error.Template
| Page being executed when the error occurred.
    Error.QueryString
| URL query string of the client's request.

Note | If you have specified`TYPE="Exception"` or `TYPE="Monitor"`, you can substitute the prefix CFERROR for Error if you prefer this form; for example, CFERROR.Diagnostics, CFERROR.Mailto or CFERROR.DateTime.

### Error pages where TYPE="Validation"

Error variables available when CFERROR uses TYPE="Validation" are as follows:

Custom Error Pages where TYPE="Validation"
Error Variable | Description
--- | ---
    Error.ValidationHeader
| Text for header of validation message.
    Error.InvalidFields
| Unordered list of validation errors that occurred.
    Error.ValidationFooter
| Text for footer of validation message.

### Example

    <!--- This example shows the use of CFERROR. --->
    <HTML>
    <HEAD>
    <TITLE>CFERROR Example</TITLE>
    </HEAD>

    <BODY>
    <H3>CFERROR Example</H3>

    <P>CFERROR provides the ability to display customized
    HTML pages when errors occur. This allows you to
    maintain a consistent look and feel within your
    application even when errors occur. Note that no CFML
    can be displayed in the resulting templates except
    for the specialized error variables.
    <P>CFTRY/CFCATCH provides a more interactive way to
    handle your CF errors within a CF template than CFERROR,
    but CFERROR is still a good safeguard against general
    errors.
    <P>You can also use CFERROR within the Application.cfm
    to specify error handling responsibilities for an entire
    application.

    <!--- Example of CFERROR call within a template --->
    <CFERROR TYPE="REQUEST"
         TEMPLATE="request_err.cfm"
         MAILTO="admin@mywebsite.com">

    <!--- Example of the template to handle this error --->
    <!---
    <HTML>
    <HEAD>
        <TITLE>We're sorry -- An Error Occurred</TITLE>
    </HEAD>

    <BODY>
    <UL>
    <CFOUTPUT>
        <LI><B>Your Location:</B> #Error.RemoteAddress#
        <LI><B>Your Browser:</B> #Error.Browser#
        <LI><B>Date and Time the Error Occurred:</B> #Error.DateTime#
        <LI><B>Page You Came From:</B> #Error.HTTPReferer#
        <LI><B>Message Content</B>: <BR><HR width=50%>
           <P>#Error.Diagnostics#<HR width=50%><P>
        <LI><B>Please send questions to:</B>
           <a href="mailto:#Error.MailTo#">#Error.MailTo#</A>
    </CFOUTPUT>
    </UL>
    </BODY>
    </HTML>        --->