cferror

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.

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

Attribute	Req/Opt	Default	Description
type	Required		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 Developing ColdFusion MX Applications. exception: a exception of the type specified by the `exception` attribute. validation: errors recognized by sever-side type validation. request: any encountered error.
template	Required		Relative path to the custom error page. (A ColdFusion page was formerly called a template.)
mailTo	Optional		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.
exception	Optional	Any	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

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 Handling Errors in Developing ColdFusion MX Applications.

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

Page Types

The following table describes the types of errors you can specify and code you can use on the pages that handle these error type.

Page type	Description	Use
Exception	Dynamically invoked by the CFML language processor when it detects an unhandled exception condition. Uses the full range of CFML tags. Error variables must be in `cfoutput` tags.	Can handle specific exception types or display general information for exceptions.
Request	Includes the error variables described in the Error Variables section. Cannot include CFML tags, but you can display values of the error variables by enclosing them in number signs (#), as in #error.MailTo#.	Use as a backup error handler to other error handling methods, including exception type.
Validation	Handles data input validation errors that occur when submitting a form that uses hidden form-field validation. Cannot include CFML tags, but you can display values of the error variables by enclosing them in number signs (#), as in #Error.InvalidFields#. You must specify the validation error handler in the Application.cfm file.	Handles hidden form-field style validation errors only.

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.

Page type	Error variable	Description
Validation only	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 MX.
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.generatedContent	The content generated by the page up to the point where the error occurred.
error.queryString	URL query string of client's request.
Exception only	error.messge	Error message associated with the exception.
error.rootCause	Java servlet 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 containing information for each tag in the tag stack. The tag stack consists of each tag that is currently open.
error.type	Exception type.

In exception error handling pages, you can access the error variables that are also available to the cfcatch tag. See cfcatch for a description of these variables. To use these variables, prefix them with "cferror."

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

Comments are no longer accepted for ColdFusion MX 6.1. ColdFusion 8 is the current version.

Comments

wlee said on Mar 26, 2004 at 8:32 AM :

We are working to improve the examples in the ColdFusion reference pages. We propose to replace the current example on this page with the the following example. If you have any comments on this example, add them to this page.

<h3>cferror Example</h3>
<p>cferror lets you display custom HTML pages when errors occur. This lets youmaintain a consistent look and feel within the application even whenerrors occur. No CFML can be displayed in the pages, except specializederror variables.
<p>cftry/cfcatch is a more interactive way to handle CF errors within a CF pagethan 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.

<cferror type = "REQUEST"
template = "request_err.cfm"
mailTo = "admin@mywebsite.com">

<cfquery name="testQuery" datasource="doesNotExist">
select * from nothing
</cfquery>


<html>
<head>
<title>We're sorry -- An Error Occurred</title>
</head>
<body>
<h2>We're sorry -- An Error Occurred</h2>
<p>
If you continue to have this problem, please contact #error.mailTo#
with the following information:</p>
<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>:
<p>#error.diagnostics#</p>
</ul>

profit11 said on May 25, 2004 at 4:21 PM :

Typo?: error.messge

parrot person said on Sep 10, 2004 at 8:03 AM :

Typo: "sever-side type validation" should be server...

murat said on Oct 7, 2004 at 2:41 AM :

Use the error.template variable.

jdugandzic said on Nov 5, 2004 at 2:24 PM :

I am trying to add some additional debugging info to my cferror pages. I need to see the sql statement that caused an error. Macromedia's docs say that 'In exception error handling pages, you can access the error variables that are also available to the cfcatch tag. See cfcatch for a description of these variables. To use these variables, prefix them with "cferror." '

This works in theory, but not for real. If I use #cferror.sql# , the error-handling page bombs out and reverts back to the original sql error and doesn't actually process my error handling. Has anyone had experience with this? Has anyone ever been able to have their error handling page show the sql statement that caused the error? This would help me greatly. I have just about every other piece of information to help me debug except this one, and it's a big one!

Thanks

jdugandzic said on Nov 5, 2004 at 2:46 PM :

Nevermind, I found that this information is partially correct. The cfcatch variables are not available, but the sql stuff is available buried deep in the cferror structure. thanks for lots of documentation on this macromedia!!!!! :(

dorange said on Nov 9, 2004 at 6:02 PM :

jdugandzic: I would like to know how did you do it. I have the same issue and for some reason cannot access Error.sql when i use my own error handling page specified by <cferror type="exception" ...>

The strange thing is that when one uses default Site-wide error handling page (i.e. without specifying <cferror>) error.sql data is available. I’ve investigated this and have discovered when a database exception is handled by the default error handler (located for me in C:\CFusionMX\wwwroot\WEB-INF\exception\coldfusion\runtime\ DatabaseException.cfm) the Error object has the following keys:

Sql,SQLState,queryError,RootCause,where,StackTrace,Detail,NativeErrorCode,Message,DataSource,ErrorCode,Type,TagContext
However, that exact same exception when i use my own error page – as specified by cferror - the error object is missing sql data and has only the following keys:

GeneratedContent,Mailto,RootCause,RemoteAddress,StackTrace,QueryString,HTTPReferer,Template,Message,Diagnostics,DateTime,Browser,Type,TagContext

This is quite an unexpected behavior and it should at least be documented if not fixed.

If someone figures out how to get Error.sql please let me know [dupublic(no/spam)@twcny.rr.com]

Dogfish88 said on Nov 12, 2004 at 5:57 PM :

You can use <cfdump var=#error#> to get all the information you want to get. And you will find out the structure of variable Error.

No screen name said on Dec 29, 2004 at 9:27 AM :

Has anyone encounter a problem of filtering custom exception types in cferror pages? When I use any unrecognized or custom exception types to filter, cferror tag lets them IN instead of OUT of my error handling page. Can anyone tell me a solutiont to this?? Thanks!

walkman said on Jun 2, 2005 at 4:07 PM :

What about page not found error?

Error Occurred While Processing Request
File not found: /property/system/123.cfm

csteinola said on Jun 17, 2005 at 12:28 PM :

It's unclear whether using CFERROR is the same as setting a site-wide error template in the CF administrator, if it is different, or just when/why you'd use one over the other.

jrunrandy said on Jun 29, 2005 at 12:35 PM :

If you're asking how to display an error template on a 404, then I think that either the Site-wide error handler or errorurl property in the web server connector are what you need. For more information on the site-wide error handler, see the CF Administrator online help; for more information on the Web server connector, see: http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/websera8.htm.

gyzer said on Sep 26, 2005 at 12:37 AM :

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

cfencode is not a tag, it is an application used to encode a cfml file

thekat said on Jun 29, 2006 at 11:32 PM :

An additional note on CFError. Despite information above to the contrary, the cferror tag does not catch all CF errors, regardless of the TYPE attribute that you specify. For example, if you leave off the closing parenthesis in the following tag: #left(sometext, 20#, the CFError will NOT trigger. However, if you properly form the tag but pass an invalid variable (for example passing a misspelling of #left(smoetext, 20)#, the error template will trigger fine. For CFError to process, there can not be any malformed CF, just malformed variables, truncation, etc.