Handling runtime exceptions with ColdFusion tags

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. Ordinarily, when ColdFusion encounters an exception, it stops processing and displays an error message, or an error page specified by a cferror tag or the Site-wide Error Handler option on the Settings page in the Administrator. However, you can use the ColdFusion exception handling tags to catch and process runtime exceptions directly in ColdFusion pages. 
This ability to handle exceptions directly in your application pages enables your application to do the following:

• Respond appropriately to specific errors within the context of the current application page
• Recover from errors whenever possible.

Exception-handling tags

ColdFusion provides the exception-handling tags listed in the following table:

Using cftry and cfcatch tags

The cftry tag lets you go beyond reporting error data to the user:

• You can include code that recovers from errors so your application can continue processing without alerting the user.
• You can create customized error messages that apply to the specific code that causes the error.
  For example, you can use cftry to catch errors in code that enters data from a user registration form to a database. The cfcatch code could do the following:

1. Retry the query, so the operation succeeds if the resource was only temporarily unavailable.
2. If the retries fail:
   • Display a custom message to the user
   • Post the data to an e-mail address so the company staff can enter the data after the problem has been solved.
     Code that accesses external resources such as databases, files, or LDAP servers where resource availability is not guaranteed is a good candidate for using try/catch blocks.

Try/catch code structure

In order for your code to directly handle an exception, the tags in question must appear within a cftry block. It is a good idea to enclose an entire application page in a cftry block. You then follow the cftry block with cfcatch blocks, which respond to potential errors. When an exception occurs within the cftry block, processing is thrown to the cfcatch block for that type of exception. 
Here is an outline for using cftry and cfcatch to handle errors:

Try/catch code rules and recommendations

Follow these rules and recommendations when you use cftry and cfcatch tags:

• The cfcatch tags must follow all other code in a cftry tag body.

• You can nest cftryblocks. For example, the following structure is valid:

  <cftry> code that may cause an exception <cfcatch ...> <cftry> First level of exception handling code <cfcatch ...> Second level of exception handling code </cfcatch </cftry> </cfcatch> </cftry>

  If an exception occurs in the first level of exception-handling code, the inner cfcatch block can catch and handle it. (An exception in a cfcatch block cannot be handled by cfcatch blocks at the same level as that block.)

• ColdFusion always responds to the latest exception that gets raised. For example, if code in a cftry block causes an exception that gets handled by a cfcatch block, and the cfcatch block causes an exception that has no handler, ColdFusion displays the default error message for the exception in the cfcatch block, and you are not notified of the original exception.
• If an exception occurs when the current tag is nested inside other tags, the CFML processor checks the entire stack of open tags until it finds a suitable cftry/cfcatch combination or reaches the end of the stack.
• Use cftry with cfcatch to handle exceptions based on their point of origin within an application page, or based on diagnostic information.
• The entire cftry tag, including all its cfcatch tags, must be on a single ColdFusion page. You cannot place the <cftry> start tag on one page and have the </cftry> end tag on another page.
• For cases when a cfcatch block is not able to successfully handle an error, consider using the cfrethrow tag, as described in Using the cfrethrow tag in Handling runtime exceptions with ColdFusion tags.

• If an exception can be safely ignored, use a cfcatchtag with no body; for example:

  <cfcatch Type = Database />

• In problematic cases, enclose an exception-prone tag in a specialized combination of cftry and cfcatch tags to immediately isolate the tag's exceptions.

Exception information in cfcatch blocks

Within the body of a cfcatch tag, the active exception's properties are available in a cfcatch object. The object contents are described as follows:

Standard cfcatch variables

The following table describes the variables that are available in most cfcatch blocks:

The cfcatch.TagContext variable contains an array of tag information structures. Each structure represents one level of the active tag context at the time when ColdFusion detected the exception. That is, there is one structure for each tag that is open at the time of the exception. For example, if the exception occurs in a tag on a custom tag page, the tag context displays information about the called custom tag and the tag in which the error occurs.
The structure at position 1 in the array represents the currently executing tag at the time the exception was detected. The structure at position arrayLen represents the initial tag in the stack of tags that were executing when the compiler detected the exception.
The following table lists the tagContext structure attributes:

Database exceptions

The following additional variables are available whenever the exception type is database:

Expression exceptions

The following variable is only available for Expression exceptions:

Locking exceptions

The following additional information is available for exceptions related to errors that occur in cflock tags:

Missing include exceptions

The following additional variable is available if a missing file specified by a cfinclude tag causes the error.

Using the cftry tag: an example

The following example shows the cftry and cfcatch tags. It uses the cfdocexamples data source, which many of the examples listed here use, and a sample included file, includeme.cfm.
If an exception occurs when you run the cfquery statement, the application page flow switches to the cfcatch type="Database" exception handler. It then resumes with the next statement after the cftry block, once the cfcatch type="Database" handler completes. Similarly, the cfcatch type="MissingInclude" block handles exceptions raised by the cfinclude tag.

Use the following procedure to test the code.

Test the code

1. Make sure that there is no includeme.cfm file and display the page. The cfcatch type="MissingInclude" block displays the error.
2. Create a nonempty includeme.cfm file and display the page. If your database is configured properly, you see an employee entry and do not get any error.

3. In the cfquerytag, change the line:

   FROM Employee

   to:

   FROM Employer

   Display the page. This time the cfcatch type="Database" block displays an error message.

4. Change Employer to Employee. Change the cfoutputline:

   <p>Department: #Dept_ID#<br>

   to:

   <p>Department: #DepartmentID#<br>

   Display the page. This time the cfcatch type="Any" block displays an error message indicating an expression error.

5. Change DepartmentID back to Dept_ID and redisplay the page. The page displays properly.Open \CFusion\Log\MyAppPage.log in your text editor. You should see a header line, an initialization line, and four detail lines, like the following:

   "Severity","ThreadID","Date","Time","Application","Message" "Information","web-0","11/20/01", "16:27:08",, "cf_root\runtime\servers\default\logs\ MyAppPage.log initialized" "Information","web-0","11/20/01","16:27:08",, "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: MissingInclude" "Information","web-1","11/20/01","16:27:32",," Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: " "Information","web-0","11/20/01","16:27:49",, "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: Database" "Information","web-1","11/20/01","16:28:21",, "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: General Exception" "Information","web-0","11/20/01","16:28:49",, "Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: "

    

Reviewing the code

The following table describes the code:

Using the cfthrow tag

You can use the cfthrow tag to raise your own, custom exceptions. When you use the cfthrow tag, you specify any or all of the following information:

All of these values are optional. You access the attribute values in cfcatch blocks and Exception type error pages by prefixing the attribute with either cfcatch or error, as in cfcatch.extendedInfo. The default ColdFusion error handler displays the message and detail values in the Message pane and the remaining values in the Error Diagnostic Information pane.

Catching and displaying thrown errors

The cfcatch tag catches a custom exception when you use any of the following values for the cfcatch type attribute:

• The custom exception type specified in the cfthrow tag.
• A custom exception type that hierarchically matches the initial portion of the type specified in the cfthrow tag. For more information, see the next section, Custom error type name hierarchy.
• Application, which matches an exception that is thrown with the Application type attribute or with no type attribute.
• Any, which matches any exception that is not caught by a more specific cfcatch tag.
  Similarly, if you specify any of these types in a cferror tag, the specified error page displays information about the thrown error.
  Because the cfthrow tag generates an exception, a Request error handler or the Site-wide error handler can also display these errors.

Custom error type name hierarchy

You can name custom exception types using a method that is similar to Java class naming conventions: domain name in reverse order, followed by project identifiers, as in the following example:

This fully qualified naming method is not required; you can use shorter naming rules, for example, myApp.Invalid_field.codeValue, or even codeValue. 
This naming method is not just a convention; ColdFusion uses the naming hierarchy to select from a possible hierarchy of error handlers. For example, assume that you use the following cfthrow statement:

Any of the following cfcatch error handlers would handle this error:

The handler that most exactly matches handles the error. In this case, the MyApp.BusinessRuleException.InvalidAccount handler runs. However, if you used the following cfthrow tag:

the MyApp.BusinessRuleException handler receives the error.
The type comparison is not case sensitive.

When to use the cfthrow tag

Use the cfthrow tag when your application can identify and handle application-specific errors. One typical use for the cfthrow tag is in implementing custom data validation. The cfthrow tag is also useful for throwing errors from a custom tag page to the calling page. 
For example, on a form action page or custom tag used to set a password, the application can determine whether the password entered is a minimum length, or contains both letters and number, and throw an error with a message that indicates the password rule that was broken. The cfcatch block handles the error and tells the user how to correct the problem.

Using the cfrethrow tag

The cfrethrow tag lets you create a hierarchy of error handlers. It tells ColdFusion to exit the current cfcatch block and "rethrow" the exception to the next level of error handler. Thus, if an error handler designed for a specific type of error cannot handle the error, it can rethrow the error to a more general-purpose error handler. The cfrethrow tag can only be used in a cfcatch tag body.

The cfrethrow tag syntax

The following pseudocode shows how you can use the cfrethrow tag to create an error-handling hierarchy:

Although this example uses a Database error as an example, you can use any cfcatch type attribute in the innermost error type. 
Follow these rules when you use the cfrethrow tag:

• Nest cftry tags, with one tag for each level of error handling hierarchy. Each level contains the cfcatch tags for that level of error granularity.
• Place the most general error catching code in the outermost cftry block.
• Place the most specific error catching code in the innermost cftry block.
• Place the code that can cause an exception error at the top of the innermost cftry block.
• End each cfcatch block except those in the outermost cftry block with a cfrethrow tag.

Example: using nested tags, cfthrow, and cfrethrow

The following example shows many of the discussed techniques including nested cftry blocks and the cfthrow and cfrethrow tags. The example includes a simple calling page and a custom tag page:

• The calling page does little more than call the custom tag with a single attribute, a name to be looked up in a database. It does show, however, how a calling page can handle an exception thrown by the custom tag.
• The custom tag finds all records in the cfdocexamples database with a matching last name, and returns the results in a Caller variable. If it fails to connect with the main database, it tries a backup database.

The calling page

The calling page represents a section from a larger application page. To keep things simple, the example hard-codes the name to be looked up.

Reviewing the code

The following table describes the code:

The custom tag page

The custom tag page searches for the name in the database and returns any matching records in a getEmpsResult variable in the calling page. It includes several nested cftry blocks to handle error conditions. For a full description, see Reviewing the code section, following the example:Save the following code as getEmps.cfm in the same directory as the calling page.

Reviewing the code

The following table describes the code:

Testing the code

To test the various ways errors can occur and be handled in this example, try the following:

• In the calling page, change the attribute name to any other value; for example, My Attrib. Then change it back.
• In the first cfquery tag, change the data source name to an invalid data source; for example, NoDatabase.
• With an invalid first data source name, change the data source in the second cfquery tag to cfdocexamples.
• Insert cfthrow tags throwing custom exculpations in various places in the code and observe the effects.