Developing ColdFusion Applications
Preventing and Handling Errors

Generating Custom Error Messages with cferror

By default, ColdFusion uses a standard page for most errors. Custom error pages allow you to 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 timeouts. 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 pages:

Type	Description
Validation	Handles server-side form field data validation errors. The validation error page cannot include CFML tags, but can display special error page variables.
Exception	Handles exception errors. You can specify different error pages for different types of exceptions.
Request	Handles any exception that is not otherwise handled. The request error page runs after the CFML language processor finishes. As a result, the request error page cannot include CFML tags, but can display error page variables. A request error page is useful as a backup if errors occur in other error handlers.
Monitor	Handles exceptions before any other error-handling mechanism runs. You can specify different monitor pages for different types of exceptions. When the monitor page completes, error handling continues with any cftry/cfcatch code or other cferror error handlers for the error type. You should only use monitor handlers for debugging, for example, to log error information, and not include them in production code.

You set the custom error application pages with the cferror tag. You can set the custom error application pages page-by-page, but because custom error pages generally apply to an entire application, it is more efficient to include the cferror tag in the Application.cfm file. After you create a custom error page, you must include the cferror tag in your application's Application.cfm page. For more information, see "Understanding the Web Application Framework".

For detailed information on the cferror tag, see the CFML Reference.

Creating an error application page

Error application pages for validation and request errors cannot use ColdFusion tags; they can only use HTML tags. Error application pages for exception and monitor errors can use all of CFML, including tags, expressions, and functions.

Even validation and request error pages have access to specific CFML error variables such as Error.Diagnostics (for request errors) and Error.InvalidFields (for validation errors). All CFML error variables start with the prefix Error. To include these variables in your HTML, surround the variable names with pound signs, but do not use the cfoutput tag; for example:

<p>

ColdFusion found the following errors in the data you entered:

</p>

#error.InvalidFields#<br>

Error page variables

The following variables are available on error pages:

Error type	Error variable	Description
Exception Request Monitor	error.type	The exception type. For a list of error types, see "Types of recoverable exceptions supported".
	error.diagnostics	Detailed error diagnostics from ColdFusion Server.
	error.mailTo	E-mail 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.
Validation	error.validationHeader	Text for header of default validation message.
	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.validationFooter	Text for footer of default validation message.

Example of a request error page

The following example shows a custom error page for a request error:

<html>

<head>

  <title>Products - Error</title>

</head>

<body>



<cfoutput>

<h2>Sorry</h2>



<p>An error occurred when you requested this page.

Please email the Webmaster to report this error. 

We will work to correct the problem and apologize

for the inconvenience.</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>

  <br>

  Diagnostics:<br>

  #error.diagnostics#

</td></tr></table>



</cfoutput>

</body>

</html>

Example of a validation error page

The following example shows a custom error page for a validation error:

<html>

<head>

  <title>Products - Error</title>

</head>

<body>



<h2>Oops</h2>



<p>You failed to correctly complete all the fields

in the form. The following problems occurred:</p>



#error.invalidFields#



</body>

</html>

Copyright © 2001, Macromedia Inc. All rights reserved.

---