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:

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