Adobe ColdFusion 8

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 application's normal flow of instructions. 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 will handle 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 you should 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, cfmodule, 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 specifically 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. For a list of advanced exception types, see "Advanced exception types" in the 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">