ColdFusion 9.0 Resources

Understanding errors

You can look at errors in many ways; for example, you can look at errors by their causes. You can also look at them by their effects, particularly by whether your application can recover from them. You can also look at them the way ColdFusion does, as follows:

About error causes and recovery

Errors can have many causes. Depending on the cause, the error can be recoverable. A recoverable error is one for which your application can identify the error cause and take action on the problem. Some errors, such as time-out errors, are recoverable without indicating to the user that an error was encountered. An error for which a requested application page does not exist is not recoverable, and the application can only display an error message.

Errors such as validation errors, for which the application cannot continue processing the request, but can provide an error-specific response, can also be considered recoverable. For example, an error that occurs when a user enters text where a number is required can be considered recoverable, because the application can recognize the error and redisplay the data field with a message providing information about the cause of the error and telling the user to reenter the data.

Some types of errors are recoverable in some, but not all circumstances. For example, your application can retry a request following a time-out error, but it must also be prepared for the case where the request always times out.

Error causes fall in the broad categories listed in the following table:

ColdFusion error types

Before you can effectively manage ColdFusion errors, you must understand how ColdFusion classifies and handles them. ColdFusion categorizes errors as detailed in the following table:

Type

Description

Exception

An error that prevents normal processing from continuing. All ColdFusion exceptions are, at their root, Java exceptions.

Missing template

An HTTP request for a ColdFusion page that cannot be found. Generated if a browser requests a ColdFusion page that does not exist.

Missing template errors are different from missing include exceptions, which result from cfinclude tags or custom tag calls that cannot find their targets.

Form field data validation

Server-side form field validation errors are a special kind of ColdFusion exception. You specify server-side form validation by using cfform attributes or hidden HTML form fields. All other types of server-side validation, such as the cfparam tag generate runtime exceptions. For more information on validating form fields see Validating Data.

ColdFusion includes a built-in error page for server-side form field validation errors, and the cferror tag includes a type attribute that lets you handle these errors in a custom error page, but if you use onError processing in Application.cfc, or try/catch error handling, the error appears as an Application exception. For more information on handling Form field validation in Application.cfc see Handling server-side validation errors in the onError method.

Note: The onSubmit and onBlur form field validation techniques use JavaScript or Flash validation on the client browser.

About ColdFusion exceptions

Most ColdFusion errors are exceptions. You can categorize ColdFusion exceptions in two ways:

When they occur
Their type

When exceptions occur

ColdFusion errors can occur at two times, when the CFML is compiled into Java and when the resulting Java executes, called runtime exceptions.

Compiler exceptions

Compiler exceptions are programming errors that ColdFusion identifies when it compiles CFML into Java. Because compiler exceptions occur before the ColdFusion page is converted to executable code, you cannot handle them on the page that causes them. However, other pages can handle these errors. For more information, see Handling compiler exceptions.

Runtime exception

A runtime exception occurs when the compiled ColdFusion Java code runs. It is an event that disrupts the normal flow of instructions in the application. Exceptions can result from system errors or program logic errors. Runtime exceptions include:

Error responses from external services, such as an ODBC driver or CORBA server
CFML errors or the results of cfthrow or cfabort tags
Internal errors in ColdFusion

ColdFusion exception types

ColdFusion exceptions have types that you specify in the cferror, cfcatch, and cfthrow error-handling tags. A cferror or cfcatch tag handles only exceptions of the specified type. You identify an exception type by using an identifier from one (or more) of the following type categories:

Basic
Custom
Advanced
Java class

Note: Use only custom error type names and the Application basic type name in cfthrow tags. All other built-in exception type names identify specific types of system-identified errors, so do not use them for errors that you identify yourself.

Basic exception types

All ColdFusion exceptions except for custom exceptions belong to a basic type category. These types consist of a broadly defined categorization of ColdFusion exceptions. The following table describes the basic exception types:

Type	Type name	Description
Database failures	Database	Failed database operations, such as failed SQL statements, ODBC problems, and so on.
Missing include file errors	MissingInclude	Errors where files specified by the cfinclude, cfmessagebox, and cferror tags are missing. (A `cferror` tag generates a missingInclude error only when an error of the type specified in the tag occurs.) The `MissingInclude` error type is a subcategory of Template error. If you do not specifically handle the MissingInclude error type, but do handle the Template error type, the Template error handler catches these errors. `MissingInclude` errors are caught at runtime.
Template errors	Template	General application page errors, including invalid tag and attribute names. Most `Template` errors are caught at compile time, not runtime.
Object exceptions	Object	Exceptions in ColdFusion code that works with objects.
Security exceptions	Security	Catchable exceptions in ColdFusion code that works with security.
Expression exceptions	Expression	Failed expression evaluations; for example, if you try to add 1 and "a".
Locking exceptions	Lock	Failed locking operations, such as when a cflock critical section times out or fails at runtime.
Verity Search engine exception	SearchEngine	Exceptions generated by the Verity search engine when processing `cfindex`, cfcollection, or cfsearch tags.
Application-defined exception events raised by `cfthrow`	Application	Custom exceptions generated by a cfthrow tag that do not specify a type, or specify the type as `Application`.
All exceptions	Any	Any exceptions. Includes all types in this table and any exceptions that are not handled in another error handler, including unexpected internal and external errors.

Note: The Any type includes all error with the Java object type of java.lang.Exception. It does not include java.lang.Throwable errors. To catch Throwable errors, specify java.lang.Throwable in the cfcatch tag type attribute.

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 for backward-compatibility.

Java exception classes

Every ColdFusion exception belongs to, and is 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 Java class of the exception.

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 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 information describes briefly how ColdFusion handles errors. Detailed information is provided in the remaining topics.

Missing template errors

If a user requests a page that 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:

If the Application CFC (Application.cfc) has an onError event handler method, ColdFusion calls the method.
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.
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.

For more information on using hidden form field validation, see Validating Data. For more information on Application.cfc, see Designing and Optimizing a ColdFusion Application.

Compiler exception errors

If ColdFusion encounters a compiler exception, how it handles the exception depends on whether the error occurs on a requested page or on an included page:

If the error occurs on a page that is accessed by a cfinclude or cfmessagebox tag, or on a custom tag page that you access using the cf_ notation, ColdFusion handles it as a runtime exception in the page that accesses the tag. For a description of how these errors are handled, see the next section, “ Runtime exception errors.”
If the error occurs directly on the requested page, and the Administrator Settings Site-wide Error Handler field specifies an error handler page, ColdFusion displays the specified error page. Otherwise, ColdFusion reports the error using the standard error message format described in Error messages and the standard error format.

Runtime exception errors

If ColdFusion encounters a runtime exception, it does the action for the first matching condition in the following table:

Condition	Action
The code with the error is inside a cftry tag and the exception type is specified in a `cfcatch` tag.	Executes the code in the cfcatch tag. If the `cftry` block does not have a `cfcatch` tag for this error, tests for an appropriate cferror handler or site-wide error handler.
The ColdFusion application has an Application.cfc with an onError method	Executes the code in the `onError` method. For more information on using the `onError` method, see Handling errors in Application.cfc.
A `cferror` tag specifies an exception error handler for the exception type.	Uses the error page specified by the `cferror` tag.
The Administrator Settings Site-wide Error Handler field specifies an error handler page.	Uses the custom error page specified by the Administrator setting.
A `cferror` tag specifies a Request error handler.	Uses the error page specified by the `cferror` tag.
The default case.	Uses the standard error message format

For example, if an exception occurs in CFML code that is not in a cftry block, and Application.cfc does not have an onError method, but a cferror tag specifies a page to handle this error type, ColdFusion uses the specified error page.