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 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.

<p><b>Header, other content etc goes here</b></p>

<cftry>
<cfquery datasource="SomeUnavailableDsn" name="getUsers">
   select FirstName from individual
</cfquery>
<cfoutput query="">#FirstName#<br /></cfoutput>
<cfcatch type="any">
  Apologies, an error has occurred. Please try again later.
</cfcatch>
</cftry>

<p><b>Footer, other content etc goes here</b></p>

The above code results in the following error message.

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:

Handling Multiple Error Types

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

<cftry>
... High risk code goes here...

<cfcatch type="Database">
  A database error has occurred. Please try again later.
</cfcatch>
<cfcatch type="Expression">
  An expression error has occurred. Please try again later.
</cfcatch>
<cfcatch type="MissingInclude">
  An include file has gone missing. Please try again later.
</cfcatch>
</cftry>

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.

<cferror type="exception" template="errors.cfm" exception="any">

The good thing about this is that, you are able to display a customized error page for errors that aren't handled by a cftry/cfcatch (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 cftry/cfcatch 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 (for example C:\CFusionMX\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.

• << Previous
• Next Lesson >>