Whatever message this page gives is out now! Go check it out!
Specifying custom error messages with the cferror tag
Last update:
May 18, 2026
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:
Type
Description
Validation
Handles server-side form field data validation errors. The validation error page cannot include CFML tags, but it can display error page variables.You can use this attribute only in the Application.cfc initialization code or on the Application.cfm page. It has no effect when used on any other page. Therefore, you can specify only one validation error page per application, and that page applies to all server-side validation errors.
Exception
Handles specific exception errors. You can specify individual 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.
Specifying a custom error page
You specify the custom error pages with the cferror tag. For Validation errors, the tag must be in the Application.cfc initialization code or 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 place these cferror tags in the Application.cfc or Application.cfm file also. For more information on using these pages, see 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 causes ColdFusion to display this page: Exception, Request, or Validation.
Exception
Use only for the Exception type. The specific exception or exception category that causes the page to display. This attribute can specify any of the types described in About ColdFusion exceptions in Understanding errors.
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 e-mail address to use to send a notification each time this type of error occurs:
<cferror type = "exception"
exception = "lock"
template = "../common/lockexcept.cfm"
mailto = "server@mycompany.com">For detailed information on the cferror tag, see the CFML Reference.
Creating an error application page
The following table lists the rules and considerations that apply to error application pages:
Type
Considerations
Validation
- Cannot use CFML tags.
- Can use HTML tags.
- Can use the Error. InvalidFields , Error.validationHeader, and Error.validationFooter variables by enclosing them with number signs (#).
- Cannot use any other CFML variables.
Request
- Cannot use CFML tags.
- Can use HTML tags.
- Can use nine CFML error variables, such as Error.Diagnostics, by enclosing them with number signs.
- Cannot use other CFML variables.
Exception
- Can use full CFML syntax, including tags, functions, and variables.
- Can use nine standard CFML Error variables and cfcatch variables. Use either Error or cferror as the prefix for both types of variables.
- Can use other application-defined CFML variables.
- To display any CFML variable, use the cfoutput tag.
The following table describes the variables available on error pages: Exception error pages can also use all of the exception variables listed in the section Exception information in cfcatch blocks in Handling runtime exceptions with ColdFusion tags. 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.
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>
<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>Example of a validation error page
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>Specific and generic exception handlers
You can use the cferror tag to define both specific exception handlers and a generic exception handler.
Specific exception handlers identify a particular exception type by using the exception attribute. A generic exception handler omits the exception attribute or uses the default any behavior.
ColdFusion first tries to match a specific handler for the exception type. If no specific custom exception handler matches, ColdFusion uses the generic exception handler, if one is defined.
Custom exception matching rules
For custom exceptions raised by cfthrow or throw(), ColdFusion applies the following rules when matching cferror exception handlers:
- Matching is case-insensitive.
- Different custom exception types can have different handlers.
- If more than one cferror tag specifies the same custom exception type, the last one replaces the earlier handler.
- If no specific custom exception handler matches, ColdFusion falls back to a generic exception handler, if one is defined.
Examples
Multiple custom handlers
<cferror type="exception" exception="TypeA" template="handlerA.cfm">
<cferror type="exception" exception="TypeB" template="handlerB.cfm">
<cferror type="exception" exception="TypeC" template="handlerC.cfm">
Replacement behavior
<cferror type="exception" exception="OrderError" template="order_error_v1.cfm">
<cferror type="exception" exception="OrderError" template="order_error_v2.cfm">
Fallback behavior
<cferror type="exception" template="generic_exception.cfm">
<cferror type="exception" exception="PaymentError" template="payment_error.cfm">
Custom message behavior
<cfscript>
try {
throw(message="Custom message", type="Expression");
writeOutput("[PASS] <br>");
} catch (any e) {
writeOutput("[FAIL] #e.message# (#e.type#)<br>");
}
</cfscript>
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
