Handling errors in Application.cfc

The following sections briefly describe how you can handle errors in Application.cfc. For more information on error pages and error handling, see Handling Errors. For details on implementing the onError method, see onError in CFML Reference.

Application.cfc error handling techniques

Application.cfc can handle errors in any combination of the following ways:

You can use try/catch error handling in the event methods, such as onApplicationStart or onRequestStart, to handle exceptions that happen in the event methods.
You can implement the onError method. This method receives all exceptions that are not directly handled by try/catch handlers in CFML code. The method can use the cfthrow tag to pass any errors it does not handle to ColdFusion for handling.
You can use cferror tags in the application initialization code following the cfcomponent tag, typically following the code that sets the application's This scope variables. These tags specify error processing if you do not implement an onError method, or if the onError method throws an error. You could implement an application-specific validation error handler, for example, by putting the following tag in the CFC initialization code:
```
<cferror type="VALIDATION" template="validationerrorhandler.cfm">
```
The ColdFusion MX default error mechanisms handle any errors that are not handled by the preceding techniques. These mechanisms include the site-wide error handler that you can specify in the ColdFusion MX Administrator and the built-in default error pages.

These techniques let you include application-specific information, such as contact information or application or version identifiers, in the error message, and let you display all error messages in the application in a consistent manner. You can use Application.cfc to develop sophisticated application-wide error-handling techniques, including error-handling methods that provide specific messages, or use structured error-handling techniques.

Note: The onError method can catch errors that occur in the onSessionEnd and onApplicationEnd application event methods. It will not display messages to the user, however, because there is no request context. The onError function can log errors that occur when the session or application ends.

Handling server-side validation errors in the onError method

Server-side validation errors are actually ColdFusion exceptions; as a result, if your application uses an onError method, this method gets the error and must handle it or pass it on to ColdFusion for handling.

To identify a server-side validation error, search the Arguments.Exception.StackTrace field for coldfusion.filter.FormValidationException. You can then handle the error directly in your onError routine, or throw the error so that either the ColdFusion default validation error page or a page specified by an cferror tag in your Application.cfc initialization code handles it.

Example: error Handling with the onError method

The following Application.cfc file has an onError method that handles errors as follows:

If the error is a server-side validation error, the onError method throws the error for handling by ColdFusion MX, which displays its standard validation error message.
For any other type of exception, the onError method displays the name of the event method in which the error occurred and dumps the exception information. In this example, because you generate errors on the CFM page only, and not in a Application.cfc method, the event name is always the empty string.

<cfcomponent>
<cfset This.name = "BugTestApplication">
<cffunction name="onError">
   <!--- The onError method gets two arguments:
         An exception structure, which is identical to a cfcatch variable.
         The name of the Application.cfc method, if any, in which the error
         happened.
   <cfargument name="Except" required=true/>
   <cfargument type="String" name = "EventName" required=true/>
   <!--- Log all errors in an application-specific log file. --->
   <cflog file="#This.Name#" type="error" text="Event Name: #Eventname#" >
   <cflog file="#This.Name#" type="error" text="Message: #except.message#">
   <!--- Throw validation errors to ColdFusion for handling. --->
   <cfif Find("coldfusion.filter.FormValidationException",
                Arguments.Except.StackTrace)>
      <cfthrow object="#except#">
   <cfelse>
      <!--- You can replace this cfoutput tag with application-specific 
            error-handling code. --->
      <cfoutput>
         <p>Error Event: #EventName#</p>
         <p>Error details:<br>
         <cfdump var=#except#></p>
      </cfoutput>
   </cfif>
</cffunction>
</cfcomponent>

To test this example, put a CFML page with the following code in the same page as the Application.cfc file, and enter valid and invalid text in the text input field.

<cfform>
   This box does Integer validation: 
   <cfinput name="intinput" type="Text" validate="integer" validateat="onServer"><br>
   Check this box to throw an error on the action page:
   <cfinput type="Checkbox" name="throwerror"><br>
   <cfinput type="submit" name="submitit">
 </cfform>

<cfif IsDefined("form.fieldnames")>
   <cfif IsDefined("form.throwerror")>
      <cfthrow type="ThrownError" message="This error was thrown from the bugTest action page.">
   <cfelseif form.intinput NEQ "">
      <h3>You entered the following valid data in the field</h3>
      <cfoutput>#form.intinput#</cfoutput>
   </cfif>
</cfif>

Note: For more information on server-side validation errors, see Validating Data.

View comments in LiveDocs