Overview of Exception Handling in ColdFusion

Ordinarily, when ColdFusion encounters an error, it stops processing. However, you can use ColdFusion's exception handling tags to catch and process exceptions in ColdFusion pages. Exceptions include any event that disrupts the normal flow of instructions in a ColdFusion page, such as failed database operations, missing include files, or developer-specified events.

In order for your code to handle an exception, the tags in question must appear within a CFTRY block. It's a good idea to enclose an entire application page in a CFTRY block, and use a CFCATCH blocks to trap potential errors. When an exception occurs within the CFTRY block, processing is 'thrown' to the CFCATCH block.

Note For cases when the error handler is not able to successfully handle the thrown error, use the CFRETHROW tag within a <CFCATCH> block.

<CFTRY>
... Add code here ...
    <CFCATCH TYPE="exception type1">
    ... Add exception processing code here ...
    </CFCATCH>
    <CFCATCH TYPE="exception type2">
    ... Add exception processing code here ...
    </CFCATCH>
    <CFCATCH TYPE="Any">
    ... Add exception processing code here ...
    </CFCATCH>
</CFTRY>

To catch errors in a single problematic SQL statement, for example, you might narrow the focus by using a CFTRY block with a CFCATCH TYPE="Database" tag, outputting the CFCATCH.State information as well.

Note Do not attempt to enclose an entire application in a CFTRY block by putting the CFTRY tag in Application.cfm because you can't be sure that there will be a matching CFTRY end tag.

See the CFML Language Reference for information on the CFTRY, CFCATCH, CFRETHROW, and CFTHROW tags.

Types of recoverable exceptions supported

ColdFusion Server supports several types of recoverable exceptions. Use the TYPE attribute in the CFCATCH tag to determine which type of exception to catch.

Types of recoverable exceptions
Type Tag(s) Notes
Application-defined exception events
CFTHROW
CFCATCH TYPE="Application" 
CFCATCH TYPE="Any"
a CFCATCH block that has no TYPE 
attribute
Raise exceptions using the CFTHROW tag (with an optional diagnostic message), then catch using CFCATCH. If you specify the type to be "APPLICATION," the CFCATCH tag catches only those custom exceptions that have been specified as having the APPLICATION type in the CFTHROW tag that defines them.
Database failures
CFCATCH TYPE="Database"
CFCATCH TYPE="Any"
Catch failed database operations, such as failed SQL statements, ODBC problems, and so on.
Template errors
CFCATCH TYPE="Template"
CFCATCH TYPE="Any"
Catch general application page errors. The tags that throw an exception of TYPE="TEMPLATE" are CFINCLUDE, CFMODULE, and CFERROR.
Missing included file errors
CFCATCH TYPE="MissingInclude"
CFCATCH TYPE="Any"
Catch errors for missing included files.
Object exceptions
CFCATCH TYPE="Object"
Catch exceptions in ColdFusion code that works with objects.
Security exceptions
CFCATCH TYPE="Security"
Raise catchable exceptions in ColdFusion code that works with security.
Expression exceptions
CFCATCH TYPE="Expression"
Catch exceptions when an expression fails evaluation.
Locking exceptions
CFCATCH tag with TYPE="Lock"
Catch failed locking operations, such as when a CFLOCK critical section times out or fails at runtime.
Custom exceptions
CFCATCH 
TYPE="your_custom_exception_type
"
Specify a custom type as well as one of the predefined types.
Unexpected internal exceptions
 CFCATCH TYPE="Any"
Catch unexpected exceptions

Specifying the type as ANY causes the ColdFusion Application Server to catch internal exceptions, memory allocation errors, and access violations, which you may not be prepared to handle.

Applications can optionally use the CFTHROW tag to raise custom exceptions. Such exceptions are caught with any of the following type specifications:

The custom_exception_type type designates the name of a user-defined type specified with the CFTHROW tag.

An exception raised within a CFCATCH block cannot be handled by the CFTRY block that immediately encloses the CFCATCH tag.