onError

Description

Runs when an uncaught exception occurs in the application.

Syntax

<cffunction name="onError" returnType="void"> 
    <cfargument name="Exception" required=true/> 
    <cfargument name="EventName" type="String" required=true/> 
    ... 
</cffunction>

See also

Method summary, Handling errors in Application.cfc in the Developing ColdFusion Applications

Parameters

ColdFusion passes the following parameters to the method:

Parameter

Description

Exception

The ColdFusion Exception object. For information on the structure of this object, see the description of the cfcatch variable in the cfcatch description.

EventName

The name of the event handler that generated the exception. If the error occurs during request processing and you do not implement an onRequest method, EventName is the empty string.

Returns

This method does not return a value; do not use the cfreturn tag.

Usage

Use this method to handle errors in an application-specific manner. This method overrides any error handlers that you set in the ColdFusion Administrator or in cferror tags. It does not override try/catch blocks.

Whether the onError method can display output depends on where the error takes place, as follows:

  • The onError method can display a message to the user if an error occurs during an onApplicationStart, onSessionStart, onRequestStart, onRequest, or onRequestEnd event method, or while processing a request.

  • The onError method cannot display output to the user if the error occurs during an onApplicationEnd or onSessionEnd event method, because there is no available page context; however, it can log an error message.

If the onError event handler is triggered by a scope-specific event method, such as onSessionStart, the error prevents further processing at the level of that scope and any lower scopes. An onError event triggered by an onSessionStart method, for example, prevents further processing in the session, but not in the application.

If an exception occurs while processing the onError method, or if the onError method uses a cfthrow tag, the ColdFusion standard error handling mechanisms handle the exception. These mechanisms include: any error handlers specified by cferror tags in the Application.cfc initialization code, the site-wide error handler specified in the ColdFusion Administrator, and ColdFusion default error page. Therefore, you can use the onError method as a filter to handle selected errors, and use other ColdFusion error-handling techniques for the remaining errors.

Example

<cffunction name="onError"> 
    <cfargument name="Exception" required=true/> 
    <cfargument type="String" name="EventName" required=true/> 
    <!--- Log all errors. ---> 
    <cflog file="#This.Name#" type="error"  
            text="Event Name: #Arguments.Eventname#" > 
    <cflog file="#This.Name#" type="error"  
            text="Message: #Arguments.Exception.message#"> 
    <cflog file="#This.Name#" type="error"  
        text="Root Cause Message: #Arguments.Exception.rootcause.message#"> 
    <!--- Display an error message if there is a page context. ---> 
    <cfif NOT (Arguments.EventName IS "onSessionEnd") OR  
            (Arguments.EventName IS "onApplicationEnd")> 
        <cfoutput> 
            <h2>An unexpected error occurred.</h2> 
            <p>Please provide the following information to technical support:</p> 
            <p>Error Event: #Arguments.EventName#</p> 
            <p>Error details:<br> 
            <cfdump var=#Arguments.Exception#></p> 
        </cfoutput> 
    </cfif> 
</cffunction>