ColdBox Global Exception Handling

Exception handling is important in web applications, and ColdBox is no exception. For more information on how to implement global exception handling, please refer to documentation and examples on the ColdBox wiki site.

In this quick guide we would like to implement global exception handling by displaying a friendly error message on-screen and emailing the stack trace and associated information to site administrator when an exception occurs.   To do so, here are the steps:

  1. Create the friendly error page
  2. Update ConfigurationCFC, i.e. ColdBox.cfc
  3. Add the handler in the onException function in Main.cfc
  4. Update the ColdBox framework

Please note I have used BootStrap and jQuery with ColdBox for front-end user experience and validations.

Create the friendly error page

Under the views\Main folder, create fail.cfm and add the following code and save it:

<div class="alert alert-danger fade in text-center">
 <a href="#" class="close" data-dismiss="alert">&times;</a>
 A problem has occurred with your last request.</p>

Update ConfigurationCFC (i.e. ColdBox.cfc)

In config/ColdBox.cfc, we need to first indicate we want to use the onException function in Main handler (Main.cfc), and then activate LogBox’s emailLog to send email when an exception occurs. Here’s the code:

// Inside ColdBox {}

//Error/Exception Handling
exceptionHandler = "main.onException",

// Inside LogBox {} in Appenders {}

emailLog = {
  properties = {
    from = "<error sender email address here>",
    to = "<error recipient email address here>",
    subject = "Errors Occurred"
  levelMax = "WARN",
  levelMin = "FATAL"

Add the handler in the onException function in the main handler (Main.cfc)

In handlers\main.cfc in function onException, add the following (after the line var exceptionBean):

// Log the exception via LogBox
log.error( rc.exceptionBean.getMessage() & rc.exceptionBean.getDetail(), rc.exceptionBean.getMemento() );

// Flash where the exception occurred
flash.put("exceptionURL", event.getCurrentRoutedURL() );

// Relocate to fail page

Update the ColdBox framework

Every time we make changes to ColdBox.cfc, we need to update the ColdBox framework so that they take effect. To do so, all we have to do is load any pages and append ?fwreinit=1, i.e.


Here’s what you should see if you browse to a URL with a missing handler, for example index.cfm/abc:


And the corresponding email message which contains the stack trace for the above exception:




Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s