Custom error pages let you control the error information that users see. You can specify custom error pages for different types of errors and handle different types of errors in different ways. For example, you can create specific pages to handle errors that could be recoverable, such as request time-outs. You can also make your error messages consistent with the look and feel of your application.
You can specify the following types of custom error message pages:
You specify the custom error pages with the cferror
tag. For Validation errors, the tag must be on the Application.cfm page. For Exception and Request errors, you can set the custom error pages on each application page. However, because custom error pages generally apply to an entire application, it is more efficient to put these cferror
tags in the Application.cfm file also. For more information on using the Application.cfm page, see Chapter 13, "Designing and Optimizing a ColdFusion Application".
The cferror
tag has the attributes listed in the following table:
Attribute |
Description |
---|---|
Type |
The type of error that will cause ColdFusion to display this page: Exception, Request, or Validation. |
Exception |
Use only for the Exception type. The specific exception or exception category that will cause the page to be displayed. This attribute can specify any of the types described in "About ColdFusion exceptions". |
Template |
The ColdFusion page to display. |
MailTo |
(Optional) An e-mail address. The cferror tag sets the error page error.mailTo variable to this value. The error page can use the error.mailTo value in a message that tells the user to send an error notification. ColdFusion does not send any message itself. |
The following cferror
tag specifies a custom error page for exceptions that occur in locking code and informs the error page of the of an e-mail address it can use to send a notification each time this type of error occurs:
<cferror type = "exception" exception = "lock" template = "../common/lockexcept.cfm" mailto = "serverr@mycompany.com">
For detailed information on the cferror
tag, see CFML Reference.
The following table lists the rules and considerations that apply to error application pages:
The following table describes the variables available on error pages:
Error page type |
Error variable |
Description |
---|---|---|
Validation |
error.invalidFields |
Unordered list of validation errors that occurred. This includes any text that you specify in the value attribute or a hidden tag used to validate form input. |
error.validationHeader |
Text for the header of the default validation message. |
|
error.validationFooter |
Text for the footer of the default validation message. |
|
Exception and Request |
error.browser |
Browser that was running when the error occurred. |
error.dateTime |
Date and time when the error occurred. |
|
error.diagnostics |
Detailed error diagnostics. |
|
error.generatedContent |
Any content that ColdFusion generated in response to the request prior to the error. |
|
error.HTTPReferer |
Page containing the HTML link to the page on which the error occurred. This value is an empty string if the user specified the page directly in the browser. |
|
error.mailTo |
E-mail address of the administrator who should be notified. This value is set in the mailTo attribute of the cferror tag. |
|
error.queryString |
URL query string of the client's request, if any. |
|
error.remoteAddress |
IP address of the remote client. |
|
error.template |
Page being executed when the error occurred. |
|
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. For more information, see "Exception information in cfcatch blocks" |
|
error.type |
Exception type. For more information, see "About ColdFusion exceptions". |
Exception error pages can also use all of the exception variables listed in the section "Exception information in cfcatch blocks". To use these variables, replace the cfcatch
prefix with cferror
or error
. For example, to use the exception message in an error page, refer to it as error.message
.
In general, production Exception and Request pages should not display detailed error information, such as that supplied by the error.diagnostics
variable. Typically, Exception pages e-mail detailed error information to an administrative address or log the information using the cflog
tag instead of displaying it to the user. For more information on using the cflog
tag, see "Logging errors with the cflog tag".
The following example shows a custom error page for a request error:
<html>
<head> <title>Products - Error</title> </head> <body> <h2>Sorry</h2> <p>An error occurred when you requested this page.</p> <p>Please send e-mail with the following information to #error.mailTo# to report this error.</p> <table border=1> <tr><td><b>Error Information</b> <br> Date and time: #error.DateTime# <br> Page: #error.template# <br> Remote Address: #error.remoteAddress# <br> HTTP Referer: #error.HTTPReferer#<br> </td></tr></table> <p>We apologize for the inconvenience and will work to correct the problem.</p> </body> </html>
The following example shows a simple custom error page for a validation error:
<html>
<head> <title>Products - Error</title> </head> <body> <h2>Data Entry Error</h2> <p>You failed to correctly complete all the fields in the form. The following problems occurred:</p> #error.invalidFields# </body> </html>