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.

Syntax

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

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.

Attributes

Attribute Req/Opt Default Description

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

Attribute	Req/Opt	Description
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

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

Exception
or
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.

Page type	Description	Use
Exception or 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.

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.

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.

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

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>