User Guide

312 Chapter 14: Handling Errors
Custom exceptions
You can generate an exception with your own type by specifying a custom exception type name,
for example MyCustomErrorType, in a
cfthrow tag. You then specify the custom type name in a
cfcatch or cferror tag to handle the exception. Custom type names must be different from any
built-in type names, including basic types and Java exception classes.
Advanced exception types
The Advanced exceptions consist of a set of specific, narrow exception types. These types are
supported in ColdFusion MX for backward-compatibility. For a list of advanced exception types,
see “Advanced Exception types” in Chapter 2, “ColdFusion Tags,” in CFML Reference.
Java exception classes
Every ColdFusion exception belongs to, and can be identified by, a specific Java exception class in
addition to its basic, custom, or advanced type. The first line of the stack trace in the standard
error output for an exception identifies the exception’s Java class.
For example, if you attempt to use an array function such as
ArrayIsEmpty on an integer
variable, ColdFusion generates an exception that belongs to the
Expression exception basic type
and the
coldfusion.runtime.NonArrayException Java class.
In general, most applications do not need to use Java exception classes to identify exceptions.
However, you can use Java class names to catch exceptions in non-CFML Java objects; for
example, the following line catches all Java input/output exceptions:
<cfcatch type="java.io.IOException">
How ColdFusion handles errors
The following sections describe briefly how ColdFusion handles errors. The rest of this chapter
expands on this information.
Missing template errors
If a user requests a page that the ColdFusion cannot find, and the Administrator Server Settings
Missing Template Handler field specifies a Missing Template Handler page, ColdFusion uses that
page to display error information. Otherwise, it displays a standard error message.
Form field validation errors
When a user enters invalid data in an HTML tag that uses onServer or hidden form field server-
side data validation ColdFusion does the following:
1. If the Application CFC (Application.cfc) has an onError event handler method, ColdFusion
calls the method.
2. If the Application.cfc initialization code or the Application.cfm page has a cferror that
specifies a Validation error handler, ColdFusion displays the specified error page.
3. Otherwise, it displays the error information in a standard format that consists of a default
header, a bulleted list describing the errors, and a default footer.