CFERROR  
Description

Displays a custom HTML page when an error occurs. This lets you maintain a consistent look and feel among an application's functional and error pages.

 
Category

Exception handling tags, Extensibility tags, Application framework tags

 
Syntax
    <cferror 
   type = "a type"
   template = "template_path"
   mailTo = "email_address"
   exception = "exception_type">

  
 
See also

cfrethrow, cfthrow, cftry

 
History

New in ColdFusion MX: the monitor option of the exception attribute is deprecated. Do not use it in new applications. It might not work, and might cause an error, in later releases.

 
Usage

Use this tag to provide custom error messages for pages in an application. You generally embed this tag in the Application.cfm file. For more information, see Administering ColdFusion MX.

In exception error handling pages, you can access the error variables of the cfcatch tag; see cftry. To do this, prefix these variables with "cferror."

To ensure that error pages display successfully, avoid using the cfencode tag to encode pages that include the cferror tag.

 
Templates (pages)

The following table describes the page to use for each type of error. (A ColdFusion page was formerly commonly called a template.)

Page type Description Use

Exceptionor Error

Dynamically invoked by the CFML language processor when it detects an unhandled exception condition.

You can specify exception-handling pages in an application, using cferror type = "exception". In the ColdFusion Administrator, you can set a site-wide error handler, to handle exceptions that are not handled by an exception-handling page.

Uses the full range of CFML tags

Request

Includes the error variables described in the Error Variables section.

As a backup error handler for sites with high user interface requirements.

Validation

Handles data input validation errors that occur when submitting a form.

Handles only hidden form-field style validation errors.

You can specify the validation page in a cferror tag, directly on the action page.

You must include the validation error handler in the Application.cfm file.

 
Error variables

The exception-handling page specified in the cferror tag template attribute, contains one or more error variables. ColdFusion substitutes the value of the error variable when an error displays.

Note: If type = "exception" or "monitor", you can substitute the prefix cferror for Error; for example, cferror.diagnostics, cferror.mailTo, or cferror.dateTime.

The following table lists error variables:

Page type Error variable Description

Exception

error.diagnostics

Detailed error diagnostics from ColdFusion Server

error.mailTo

E-mail address (same as value in cferror.MailTo)

error.dateTime

Date and time when error occurred

error.browser

Browser that was running when the error occurred

error.generatedContent

Failed request's generated content

error.remoteAddress

IP address of remote client

error.HTTPReferer

Page from which client accessed link to page where error occurred

error.template

Page executing when error occurred

error.queryString

URL query string of client's request

Validation

error.validationHeader

Validation message header text

error.invalidFields

Unordered list of validation errors

error.validationFooter

Validation message footer text

Request and Exception

error.diagnostics

Detailed error diagnostics from ColdFusion Server

error.mailTo

E-mail address (same as value in cferror.MailTo)

error.dateTime

Date and time when error occurred

error.browser

Browser that was running when error occurred

error.remoteAddress

IP address of remote client

error.HTTPReferer

Page from which client accessed link to page where error occurred

error.template

Page executing when error occurred

error.queryString

URL query string of client's request

Exception only

error.messge

Error message associated with the exception.

 

error.rootCause

Java servelet exception reported by the JVM as the cause of the "root cause" of the exception. This variable is a Java object.

 

error.tagContext

Array of structures structure containing information for each tag in the tag stack The tag stack consists of each tag that is currently open.

 

error.type

Exception type.

 
Example
<h3>cferror Example</h3>
<p>cferror lets you display custom HTML pages when errors occur. This lets you
maintain a consistent look and feel within the application even when
errors occur. No CFML can be displayed in the pages, except specialized
error variables.
<p>cftry/cfcatch is a more interactive way to handle CF errors within a CF page
than cferror, but cferror is a good safeguard against general errors.
<p>You can also use cferror within Application.cfm to specify error 
handling responsibilities for an entire application.
<!--- Example of cferror call within a page --->
<cferror type = "REQUEST"
    template = "request_err.cfm"
    mailTo = "admin@mywebsite.com">
<!--- Example of the page 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>
TYPE  
  Required
 

Type of error that the custom error page handles:

  • application: application exceptions
  • database: database exceptions
  • template: ColdFusion page exceptions
  • security: security exceptions
  • object: object exceptions
  • missinginclude: missing include file exceptions
  • expression: expression exceptions
  • lock: lock exceptions
  • custom_type: developer-defined exceptions, defined in the cfthrow tag
  • any: all exception types
TEMPLATE  
  Required
 

Relative path to the custom error page. (A ColdFusion page was formerly called a template.)

MAILTO  
  Optional
 

E-mail address. Value for the error page variable error.mailto. Available to a custom error page; for example: #error.mailTo#.

EXCEPTION  
   
 

Type of exception that the tag generates:

  • an exception of the cftry tag; see cftry
  • a custom exception, coded in a cfthrow tag