cferror

Description

Enables the display of customized HTML pages when errors occur. This lets you 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">

Attributes

Attribute

Description

type
Required. The type of error that the custom error page handles.

Template
Required. The relative path to the custom error page.

mailTo
Optional. The e-mail address of the administrator to notify of the error. The value is available to your custom error page in the MailTo property of the error object. For example: #error.mailTo#.

exception
Required. Type of exception. Required if type = "exception" or "monitor".

Attribute	Description
type	Required. The type of error that the custom error page handles.
Template	Required. The relative path to the custom error page.
mailTo	Optional. The e-mail address of the administrator to notify of the error. The value is available to your custom error page in the MailTo property of the error object. For example: `#error.mailTo#`.
exception	Required. Type of exception. Required if `type = "exception"` or `"monitor"`.

Usage

Use the cferror tag to customize error messages for all the pages in an application. You generally embed the cferror tag in the Application.cfm file. For more information, see Advanced ColdFusion Administration.

To ensure that error pages display successfully, do not use the cfencode utility to encode pages that include cferror.

Templates

The following table describes the template to use for each type of error.

Template type

Description

Use

Exception
Dynamically invoked by the CFML language processor when it detects an unhandled exception condition.
You can specify exception-handling templates in several ways:

As part of an application using cferror type = "exception"

Using the ColdFusion Administrator

Uses the full range of CFML tags, making it more powerful than cferror type = "request".

Request
Includes only the error variables described in the Usage section. Cannot include CFML tags.
Use as a backup error handler for sites with high user interface requirements.

Validation
Handles data input validation errors that occur when submitting a form.
You must include the validation error handler in the Application.cfm file.

Monitor
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.
Use for monitoring and debugging exception handling within complex applications.

Template type	Description	Use
Exception	Dynamically invoked by the CFML language processor when it detects an unhandled exception condition. You can specify exception-handling templates in several ways: As part of an application using `cferror type = "exception"` Using the ColdFusion Administrator	Uses the full range of CFML tags, making it more powerful than `cferror type = "request"`.
Request	Includes only the error variables described in the Usage section. Cannot include CFML tags.	Use as a backup error handler for sites with high user interface requirements.
Validation	Handles data input validation errors that occur when submitting a form.	You must include the validation error handler in the `Application.cfm` file.
Monitor	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.	Use for monitoring and debugging exception handling within complex applications.

Error variables

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

The following table lists the error variables:

Template type

Error variable

Description

Exception
Request
Monitor

error.diagnostics
Detailed error diagnostics from ColdFusion Server.

error.mailTo
E-mail address of administrator 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.

Validation

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.

Template type	Error variable	Description
Exception Request Monitor	error.diagnostics	Detailed error diagnostics from ColdFusion Server.
error.mailTo	E-mail address of administrator 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.
Validation	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.

Note

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

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