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 email address so the data could be entered by company staff 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:

<cftry>
   Put your application 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 appropriate for all other exceptions
here ...
   </cfcatch>
</cftry>

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 cftry blocks. 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 will display the default error message for the exception in the cfcatch block, and you will not be 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 put 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.
• If an exception can be safely ignored, use a cfcatch tag with no body; for example:

  <cfcatch Type = Database />
  

• In particularly problematic cases, you might 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 following sections describe the object contents.

Standard cfcatch variables

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

cfcatch.Detail

cfcatch.ErrorCode

cfcatch.ExtendedInfo

cfcatch.Message

cfcatch.RootCause

cfcatch.TagContext

cfcatch.Type 

Note: If you use cfdump to display the cfcatch variable, the display does not include variables that do not have values.

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(cfcatch.tagContext) 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:

cfcatch.NativeErrorCode

cfcatch.SQLState

cfcatch.Sql

cfcatch.queryError

cfcatch.where

Expression exceptions

The following variable is only available for Expression exceptions:

cfcatch.ErrNumber

Locking exceptions

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

cfcatch.lockName

cfcatch.lockOperation

Missing include exceptions

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

cfcatch.missingFileName

View comments in LiveDocs