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.

History

ColdFusion MX: Deprecated the monitor option of the exception attribute. It might not work, and might cause an error, in later releases.

Syntax

<cferror  
    template = "template path" 
    type = "exception|validation|request" 
    exception = "exception type" 
    mailTo = "e-mail address">

Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

Attributes

Attribute	Description	Required	Default
exception	Type of exception that the tag 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. For more information on exception types, see cftry.	Optional	any
mailTo	An e-mail address. This attribute is available on the error page as the variable error.mailto. ColdFusion does not automatically send anything to this address.	Optional
template	Relative path to the custom error page. (A ColdFusion page was formerly called a template.)	Required
type	Type of error that the custom error page handles. The type also determines how ColdFusion handles the error page. For more information, see Specifying a custom error page in the Developing ColdFusion Applications. exception: an exception of the type specified by the exception attribute. validation: errors recognized by server-side type validation. request: any encountered error.	Required

Usage

Use this tag to provide custom error messages for pages in an application. This lets you maintain a consistent look and feel within the application, even when errors occur.
You generally embed this tag in your Application CFC or Application.cfm file to specify error-handling responsibilities for an entire application. You must put it in one of these files if you specify type="validation"; ColdFusion ignores it on any other page.
The cftry and cfcatch tags provide a more interactive way to handle ColdFusion errors within a ColdFusion page than the cferror tag, but the cferror tag is a good safeguard against general errors.
To ensure that error pages display successfully, avoid using the cfencode utility to encode pages that include the cferror tag.

Example

<h3>cferror Example</h3> 
 
<!--- Example of cferror call within a page. 
         NOTE: If you use cferror type="VALIDATION" you MUST put it in 
         Application.cfc or Application.cfm ---> 
<cferror type = "REQUEST" 
template = "request_err.cfm" 
mailTo = "admin@mywebsite.com"> 
<!--- This query calls a non-existent datasource, triggering an error to be handled. ---> 
<cfquery name="testQuery" datasource="doesNotExist"> 
select * from nothing 
</cfquery> 
 
<!--- Example of the page (request_err.cfm) to handle this error. ---> 
<html> 
<head> 
<title>We're sorry -- An Error Occurred</title> 
</head>  
<body> 
<h2>We're sorry -- An Error Occurred</h2> 
 
If you continue to have this problem, please contact #error.mailTo# 
with the following information:</p> 
 
<ul> 
<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>: 
#error.diagnostics#</p> 
</ul>

cfmldocs