ColdFusion Error Handling

Regardless of how well you test your ColdFusion applications, there will undoubtedly be times where an exception occurs in your application.

An exception is when something occurs out of the ordinary. Often, this will result in a nasty looking error message being presented to the user. You have probably seen the types of error messages that ColdFusion presents when something goes wrong - although these can be very useful to us as developers, it's probably enough to scare most users away from your website!

You can use error handling techniques to display a more user friendly error message to the user. You can still present your header and footer as you normally would, as well as any other content that was on the page, right up until the error occurred as well as after the error.

ColdFusion categorizes errors into three categories:

ColdFusion provides a number of error handling tools to assist developers in catching errors and performing another action accordingly.

Error Handling With <cftry> and <cfcatch>

You can use ColdFusion's <cftry> tag in conjunction with the <cfcatch> tag to "catch" the error before the user sees it, and display a more user friendly message to the user.

How this works is, once you identify high risk code, you nest that code inside the <cftry></cftry> tags. Then, just below the high risk code (but before the closing <cftry> tag, you insert <cfcatch></cfcatch> tags. In between these <cfcatch> tags, you specify what needs to take place if there's an error.

Example

In this example, we are attempting to perform a query against a database, then present the results. For the sake of this example, the database happens to reside on another server, but there's a problem with the network and therefore the database server is temporarily unavailable.

In this case, we have caught the error and presented a message to the user. If we hadn't done this, we would have seen the standard ColdFusion error message.

The above code results in the following error message.

Header, other content etc goes here

Apologies, an error has occurred. Please try again later.

Footer, other content etc goes here

Exception Types

You may have noticed that in the above example, the <cfcatch> tag contains a type attribute. This attribute allows you to specify which exception types should be caught by this <cfcatch> tag. This can be useful because, you may want to display a different error message depending on the type of error that occurred. The following table outlines the different exception types:

Exception NameDescription
ApplicationThese errors can occur if you call a component that doesn't exist or if there's a problem with accessing it.
DatabaseThese are errors that occur from a database call.
SecurityErrors related to Sandbox Security.
ObjectErrors resulting from a call to an object such as COM, CORBA, or Java objects.
MissingIncludeErrors resulting from a call to a missing include file or custom tag (i.e. called from a cfinclude or cfmodule tag.
TemplateErrors resulting from a call to a missing template. Similar to the MissingInclude error.
ExpressionErrors resulting from an invalid expression. This includes errors resulting from attempting to use a variable that doesn't exist.
LockErrors resulting from the cflock tag. Either the lock timed out, or it couldn't be created. Note: To receive this error, the cflock tag needs to have ThrowOnTimeout="yes".
SearchEngineErrors resulting from the cfsearch, cfindex, or cfcollection tags.
AnyUsing this value catches all of the above errors.

Handling Multiple Error Types

To handle more than one error type, you simply use a different <cfcatch> for each type you want to handle.

The <cferror> Tag

As well as using <cfcatch> and <cftry>, you can use the <cferror> tag for catching errors.

The <cferror> tag allows you to specify a generic template file that will handle any errors that occur. Usually, you would place this tag into your Application.cfm file. That way, it will automatically handle any error that occurs throughout your application.

The following example assumes a template called errors.cfm has already been created.

The good thing about this is that, you are able to display a customized error page for errors that aren't handled by a <cfcatch>/<cftry> (it's unrealistic to wrap your whole application within a <cftry>). The disadvantage is that it might be a bit harder to diagnose any problems. That's why you should still use <cfcatch>/<cftry> for blocks of code you think are vulnerable to an error occurring, but also have the cferror as a backup for other errors.

The Site-wide Error Handler

You can specify a site-wide error handler in case the previous methods didn't catch the error. The site-wide error handler is specified via the ColdFusion Administrator (under Server Settings > Settings).

The Missing Template Handler

The ColdFusion Administrator enables you to specify a missing template handler. This option is located on the same screen as the site-wide error handler (above). The missing template handler is a generic template you can use in case the application can't find a template.

Log Files

If you become aware that an error occured on your application, you can check the ColdFusion log files to find out details of the error. You can view ColdFusion's log files via the ColdFusion Administrator (under Debugging & Logging > Log Files), or by navigating to the log file folder. This is usually under cf_root\logs.

It's a good idea to review the ColdFusion log files occasionally in case there are any errors that are going unnoticed (or at least, unreported!).

Email Alerts

It's a good idea to set up email alerts that notify the technical support team whenever an error occurs with your application. Otherwise, you might never know there's a problem until eventually one of your users decides to complain!

You can set up an email alert by using ColdFusion's <cfmail> tag.