Exception handling boils down to a single question: “What do you do if something occurs out of the ordinary?” If your database throws an error because you input bad data, exception handling determines how your system reacts. If CFHTTP throws an error because it can’t connect to a remote system, exception handling enables you to gracefully recover. No ColdFusion application is complete without at least some plan for how to handle exceptions. This article shows you the many things that you can do with exception handling, as well as how to pull these techniques together into a consolidated framework that enables your application to gracefully recover from almost any error. If an error occurs in your ColdFusion code, it normally stops page execution and outputs the standard ColdFusion error page, which shows what happened and where. Structured exception handling enables you to catch the error before the user sees it and do something different, depending on the circumstances of the error. Whenever something goes wrong in your application, it throws an error. You can choose to leave this error as is so that the user can see it, or you can catch the error and handle it yourself. You catch errors so that you can handle them as exceptions to the normal execution of a request. This is the essence of exception handling. The structured part of structured exception handling refers to the natural structure of ColdFusion’s exception framework. Notice that we depict the error-handling framework as a series of sieves, in which the top level of sieves (CFCATCH) catches expected errors, with any unexpected errors “falling through” to the next level, which is handled by a collection of CFERROR templates that handle specific errors. If an error falls through the CFERROR layer, or if no CFERROR is specified to handle the error, ColdFusion’s site-wide error handler catches the error. If you have no site-wide error handler, the error falls through to the user in its raw form. Structured exception handling is not always in effect. Suppose, for example, that an error occurs with the following code:

<cfquery name=”MyQuery”
   datasource=”#Request.MainDSN#”>
   ...
 </cfquery>

The error is not caught, because structured exception handling is not yet in effect, and the user sees the standard error message. Before you can catch the error, you must tell ColdFusion to try to catch an error:

<cftry>
   <cfquery name=”MyQuery”
   datasource=”#Request.MainDSN#”>
   ...
   </cfquery>
   <cfcatch type=”Any”>
   <!--- Handle the error --->
   </cfcatch>
   </cftry>

CFTRY tells ColdFusion to watch the enclosed block of code for errors, and CFCATCH tells ColdFusion what to do if an error occurs. CFCATCH type=”Any” tells ColdFusion that any error causes execution to pass to the code within that specific CFCATCH block. CFCATCH takes a single attribute named type, which specifies the type of error that is caught. If you want to catch only database errors, for example, you can use the following code:

<cftry>
   <cfquery name=”MyQuery”
   datasource=”#Request.MainDSN#”>
   ...
   </cfquery>
   <cfcatch type=”Database”>
   <!--- Only database errors cause this code to be run --->
   </cfcatch>
   </cftry>

If you use this CFTRY/CFCATCH construct, all database errors are caught and handled by the code within the CFCATCH tag pair, and all nondatabase errors fall through to the next level in your application’s structured exception-handling framework. By specifying an advanced exception type as the argument to CFCATCH’s type attribute, you can catch and handle very specific errors that occur outside the boundaries of ColdFusion Server. The point of having this many error types is that your structured exception handling can granularly respond to each type in a specific way. You could, for example, have an exception handler that catches two different types and handles them two different ways, as follows:

<cftry>
   ... Code to execute goes here ...
 <cfcatch type=”Database”>
 A database error occurred.
 </cfcatch>
 <cfcatch type=”Expression”>
 An expression error occurred
 </cfcatch>
 </cftry>

The preceding example catches either a Database error or an Expression error and outputs a different message depending on which one. If the error is not a Database or Expression error, the error is not caught and the user sees the standard message output. CFCATCH type=”Any” cannot catch one kind of error. Specifically, type=”Any” catches any error deriving from the Java class java.lang.Exception. type=”Any” does not, however, catch errors deriving from java.lang.Throwable. To catch these errors, you must define a special CFCATCH, as follows:

<cftry>
   ...
 <cfcatch type=”java.lang.Throwable”>
 ...
 </cfcatch>
 </cftry>

You rarely encounter this type because none of the standard ColdFusion features throw this type of error. You may be surprised to learn that that you can’t catch certain errors at all. The following code, for example, throws an error regardless of the CFTRY surrounding the bad code:

<cftry>
   <cfset>
   <cfcatch type=”Any”>
   An error occurred!
   </cfcatch>
   </cftry>

The CFSET has no content, so ColdFusion throws an error stating, Invalid CFML Construct Found on line 9 at column 7. This result may seem strange, however, because you have a CFTRY and CFCATCH type=”Any”. The problem here is that the bad CFSET created a compiletime error, which can’t be caught with CFCATCH. CFCATCH can catch only a run-time error, which occurs during the execution of the template. In the case of the preceding snippet, ColdFusion couldn’t successfully parse and compile the page, so the exception handling didn’t take effect. If you were to CFINCLUDE a page with a compile-time error, the calling page could catch a Template type error. This is rare, and you should be careful not to rely on exception handling to catch compile-time errors. The short answer is anything! You can handle an error any way that you see fit, from ignoring it completely to examining it in fine detail, to rerouting the user to an alternative template. You usually do one of two things, however. Either redirect the user to a different page or display a user-friendly message telling him what happened. You can follow either of two philosophies in redirecting the user. The first is to have a specific error page for each error that can occur and redirect the user to that specific page, as in the following example:

<cftry>
   ...
 <cfcatch type=”Database”>
 <cflocation url=”dberror.cfm”>
 </cfcatch>
 </cftry>

The downside to this approach is that you can’t tell exactly what happened and why. A better option is redirect the user to an error page, but pass the error message in the URL, as follows:

<cftry>
   ...
 <cfcatch type=”Database”>
 <cflocation
 url=”error.cfm?msg=#URLEncodedFormat(CFCATCH.Message)#”>
 </cfcatch>
 </cftry>

This code passes a detailed error message in a URL parameter to the error page. Another option is to directly display some type of message rather than redirecting the user, as follows:

<cftry>
   ...
 <cfcatch type=”Database”>
 A database error occurred.
 <cfabort>
 </cfcatch>
 </cftry>

You may notice that the preceding code adds a CFABORT after the message; you don’t want the errored page to continue execution after an error occurs. A final option that is rarely used is to ignore the error. This is usually appropriate only if you are expecting an error to occur, but it doesn’t matter to you whether the error occurs or not, as the following code shows:

<cftry>
   ...
 <cfcatch type=”Database”>
 <!--- Ignore this error --->
 </cfcatch>
 </cftry>

If you’re ignoring an error, adding a comment to the CFCATCH block is usually a good idea so that you’re not confused if you go back and read your code later. And be aware that ignoring an error can prove dangerous, because you may end up inadvertently catching a more serious error than the one you were expecting. At least logging the error by using CFLOG may be a good idea, even if you plan to ignore it, as in the following example:

<cftry>
   ...
 <cfcatch type=”Database”>
 <!--- Ignore this error, but log it in case there is a legitimate
 error --->
 <cflog log=”Application” text=”#CFCATCH.Message#”>
 </cfcatch>
 </cftry>

This way, you can review the specific error in the log file.