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.
<CFERROR TYPE="Request" or "Validation" or "Monitor" or "Exception" TEMPLATE="template_path" MAILTO="email_address" EXCEPTION="exception_type">
Required. The type of error that this custom error page is designed to handle:
Application.cfm
file.
See the table under CFERROR Error Variables for information about the variables and other constructs available from the templates used to handle each type of error.
Required. The relative path to the custom error handling page. The following table describes the template to use for each type of error.
Types and Their Corresponding Custom Error Pages | |
---|---|
Type | Custom Error Page |
Exception | An exception-handling template that is dynamically invoked by the CFML language processor when it detects an unhandled exception condition. Exception-handling templates may be specified as part of an application, via the <CFERROR TYPE="Exception"> tag, or may be set via the ColdFusion Administrator. An exception-handling template can use the full range of CFML tags, making it significantly more powerful than <CFERROR TYPE="Request">. This template also has access to the error variables in the table under CFERROR Error Variables. |
Types and Their Corresponding Custom Error Pages (Continued) | |
---|---|
Type | Custom Error Page |
Request | This template can include only the error variables described in the table under CFERROR Error Variables and cannot include CFML tags. It is useful as a backup error handler for sites with high user interface requirements. |
Validation |
A validation error handler. It handles data input validation errors that occur when submitting a form. It is useful only if placed inside the Application.cfm file.
|
Monitor | An exception-monitoring template is 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. Exception-monitoring templates are useful for monitoring and debugging exception handling within complex applications. |
Optional. The email address of the administrator who should be notified of the error. This value is available to your custom error page using the MailTo property of the error object, such as #Error.MailTo#.
Required if the type is specified as Exception or Monitor. The type of exception.
The CFERROR tag is normally used to customize the error messages for all the pages in an application. As a result, you generally embed it in the Application.cfm
file. For more information about the Application.cfm
file, refer to Developing Web Applications with ColdFusion.
To help ensure that error pages display successfully, pages you specify with CFERROR should not be encoded with the cfencode
utility.
The exception-handling template specified in the TEMPLATE attribute of the CFERROR tag may contain one or more error variables, which will be substituted by ColdFusion when an error is displayed.
The following error variables are available when CFERROR specifies TYPE="Request", TYPE="Exception" or TYPE="Monitor":
Variables for Request, Exception, and Monitor Types | |
---|---|
Error Variable | Description |
Error.Diagnostics | Detailed error diagnostics from ColdFusion Server. |
Error.MailTo | Email address of administrator who should be 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. |
Note | If you have specified TYPE="Exception" or TYPE="Monitor" , you
can substitute the prefix CFERROR for Error if you prefer this form; for
example, CFERROR.Diagnostics, CFERROR.Mailto or
CFERROR.DateTime.
|
Error variables available when CFERROR uses TYPE="Validation" are as follows:
Custom Error Pages where TYPE="Validation" | |
---|---|
Error Variable | Description |
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. |
<!--- 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> --->