Kakapo : ColdFusion Exception Manager App

Kakapo is now IronGate. Go to the latest version here.

No matter how intensively we test our applications, the majority of errors occur while our applications are live. If you have an exception handler set up in your application, it may tell you when an error is waiting to be fixed, but it also provides you little information about why and how the error occurred. If you don’t have an expectation handler, you won’t even be aware of the errors occurring in your website until one of the site’s users lets you know. Either way, troubleshooting errors in complex applications can be extremely difficult, especially when you have little evidence of their causes.

Kakapo is an enhanced ColdFusion Exception Manager, built using ColdFusion. When an error occurrs anywhere, and at anytime, in your website, Kakapo takes a panoramic snapshot of the error and its surroundings, imagine a CCTV camera recording a crime scene - and then it provides you with the detailed information you need to troubleshoot the easily and successfully.


  • Record Errors
    When an error occurred in your website, Kakapo record it in familiar Robust ColdFusion Error Message interface.
  • Record Variables
    When an error occurs, not only Kakapo record error details, Kakapo take a snapshot of all Session, Cookie, Request, CGI, Form, URL and Variables providing you with every information you need for easy troubleshooting.
  • Notifies You
    Kakapo will email you when every time an error occurred in your application.
  • Set Custom Error Message
    Enter custom error message in to Kakapo and it will display that to users when an error occurs, instead standard ColdFusion error message.
  • Robust Error message for Developers
    Provide IP address(s) of development environment, Kakapo will display robust error messages to developers; even when robust error messaging is disabled in your shared hosting environment. And your users, they still see the friendly custom error message.
  • Organization
    Kakapo indentifies similar errors and groups incidence together, providing you with occurrence count, list of similar errors in other templates or other errors in the same template. Also it let you color code errors for better organization.
  • Import & Export.
    Have you ever tried to explain the error you are having to a fellow developer? Trying to recreate it? Now you don't have to. Export exception log file form Kakapo and send to send it to your friend. Your friend can import into his/her Kakapo setup and get an clear view of the exception.


  • ColdFusion 7/8/9 or Railo (ColdFusion 6.1 testing pending)
  • Working DSN to mySQL/MSSQL or PostgreSQL database (Kakapo Uses only a single table)
  • CFFILE read,write and delete access

Kakapo is extremely easy to setup.
Download the zip file at the end of the page. Unzip it into your website root, browse to the folder and then follow the on screen instructions. Don’t forget to add Kakapo to your Application.cfc or cfm file at the end of the setup.


  • Current Version 1.00
  • 08/22/2012 Import/Export Function Added. Mail settings updated. Interface change.
  • 11/19/2012 Beta 0.38
  • 08/22/2012 (kakap.cfc) kakapo_wddxsafe() updated. meta data collected on objects.
  • 08/03/2012 (kakap.cfc) Error statues code added to error page header
  • 11/19/2011 Beta 0.37
  • 11/19/2011 (Administrator/Bin) Railo fix
  • 09/25/2011 Beta 0.36
    09/25/2011 (kakapo.cfm) Email link error fixed (Thanks Srinivas Tumma)
  • 09/22/2011 Beta 0.35
    09/22/2011 (Administrator) Interface Update.
    07/08/2011 (Installation) Bug fix for pre-MX.
  • 07/08/2011 (Administrator) Bug fix on Setting Update Page.
    07/08/2011 (Installation) Bug fix for PostgreSQL.
  • 10/04/2011 Beta 0.33
    10/04/2011 (Administrator) Bug fix on Page Navigation.
  • 10/04/2011 Beta 0.32
    10/04/2011 (Administrator) Minor Bug fix on record Delete.
  • 28/03/2011 Beta 0.31
    07/03/2011 (Kakapo.cfm) Bug fix on catching multiple expectations in single page.
  • 15/03/2011 Beta 0.30
    07/03/2011 (Thanks Ed Lamp for this update)
    (Kakapo.cfm) Now capable of including inside <cfcatch></cfcatch> block and record <try><cfcatch> events.
    eg: <cfcatch><cfinclude template="kakapo/kakapo.cfm"></cfcatch>
    SQL 'where clue' recorded and SQL error display improved
    (errormsg.cfm) SQL error display improved
    (act_settings.cfm) Extra line space error improvement
  • 24/12/2010 Beta 0.13 
    (Instllation Page_2.cfm) Extra line break bug amended
    (act_settings.cfm) Extra line break bug amended
    (Kakapo.cfm) CF7 and earilyer, Bug fixed. cfwddx seems to hang the server on xml data. safety function added.
  • 18/01/2011
    (Instllation Page_1.cfm) Improvments for Railo
    (Instllation Page_3.cfm) DSN Validation added
  • 28/12/2010
    (Instllation Page_1.cfm) Improvments for Linux.
    (Instllation Page_2.cfm) Bug fixes on Linux.
    (Instllation Page_5.cfm) Message added and directory delete function disabled for Linux.
    (qry_markAsRead.cfm) Deferent Version of MySQL handle bit fields deferently. <cfqueryPARAM> to rescue.
    (kakapo.cfm) folder path format changed to be compatible with linux.
  • 25/12/2010
    (Instllation Page_1.cfm) CGI variables changed to compatible with Railo.
    ID attributes to input fields. Railo does not add ID automatically in to cfinput fields.
    (kakapo.cfm) Railo moved down in to CF7 Level. Railo cfwddx failed to encode XML, just like CF7.
    (DSP_This.cfm) Jquery code added to mimic coldfusion cfdump for railo cfdump. further updates requireds.
  • 24/12/2010 Beta 0.12 
    (Dsp_This.cfm) Validate WDDX before convert to CFM.  
    (DSP_Settings.cfm) Displays Current IP Address.
    (kakapo.cfm) Email Notification Moved to none-developer IP set. Developers wont get email notifications on errors generated by them. (Reduces repeating error notifications)
    "IP address list" label updated.
  • 23/12/2010 Beta 0.11
    (DSP_Settings.cfm) New Version Check Added
  • 22/12/2010 Beta 0.01
  • Installation Demo (Demo installation will not be deleted automatically)
  • Administrator Demo

Kakapo is named after a beautiful, critically-endangered, parrot species from New Zeeland – Kakapo , or Strigops habroptila. Learn More...

Download (kakapo.zip)
Friday 19 October 2012 11:06 AM
I tried to install the new version (1.00).

The installation was complete successfully. I have a problem: when I try to connect to the administration page (/kakapo/ administrator/) I get out of the error:

Variable SESSION is undefined.

The error occurred in C:\inetpub\website.com\classi\kakapo\administrator\system\header.cfm: Line 22 Called from C:\inetpub\website.com\classi\kakapo\administrator\index.cfm: line 12

22 : <cfif StructKeyExists(session,'msg') and not StructKeyExists(session,'error')>

IIS7, WIN 2008 Server, CF 9.0.1
Friday 19 October 2012 04:08 PM
It is looks like session management is disabled in your application. If that is the case, you can remove that <cfif> condition
Saturday 20 October 2012 10:31 AM
It looks like everything should be find. Can you do an simple dump <cfdump var="#session#"> and see what returns? you can add that on top of header.cfm page or any new page in the same folder.

Saturday 20 October 2012 07:19 AM
I tried to add <cfapplication name="GetLeadApp" sessionmanagement="yes"> in application.cfm, but it does not work.

Saturday 20 October 2012 03:30 AM
sessions are active: http://localhostr.com/file/rL3bhOiyoCIr/session.png

is set right?

Thursday 09 August 2012 09:19 AM
Hi Saman,
I am impressed with your your Teapot blog and testing it out. I am seeing this error in the logs:

08/09 07:44:02 Error [jrpp-44845] - Invalid CFML construct found on line 19 at column 1.ColdFusion was looking at the following text:<p><</p><p>The CFML compiler was processing:< marks the beginning of a ColdFusion tag.Did you mean LT or LTE? The specific sequence of files included or processed is: D:\home\sparecube.com\wwwroot\blog\administrator\js\ork.cfc, line: 19

Any ideas to correct.
Thursday 09 August 2012 08:01 PM
Hello Henry,

Can you give me the url string of the location that create this issue? and is this happened when you creating a new post?

John Skrotzki
Friday 27 July 2012 07:12 PM
One problem ( with an easy fix ):
1) An ajax request is made and the ajax handler includes an on error function
2) request fails
3) because there is no http error status code sent, the on error function will NOT be called as a 200 status code is sent

You can add a cfheader statuscode = 500 statustext = server error to the kakapo.cfm file.
Monday 30 July 2012 09:06 PM
Hello John, If ajax handler intercept the error, kakap or anything else wont be able to catch the error from the cf end. When web server generate error code, coldfusion already lost control of variables and instance.
Friday 13 April 2012 05:13 PM
Another one. When there's a "struct" variable in the request or session variable, it's not stored in kakapo. It is shown as "[undefined struct element]"

It could really be useful to store it. If I had some time, I'd do the modification myself..! :)
Wednesday 22 August 2012 11:27 PM
I know it is bit late. but made some updates on this issue.
Friday 07 September 2012 09:10 AM
Thanks! I tested it and now it show somes strings, it seems to miss things... It show "structs", but not "component".

When a CFC is assign to a struct, it is created as component and all "this." variables are assigned to it. If I do a "CFDUMP" on the struct, it is in "red". I'll try to fix it if I get a chance.

Friday 13 April 2012 07:07 PM
Hi Daniel, What's the OS/CF ver?
Monday 14 May 2012 01:09 PM
Open Kakapo.cfc – Go to line 383, Variable collection starts there & it converted to a WDDX at line 446 and ends. You need to look at code in-between, specifically between 399 to 406 – since we are tackling a session variable.

Dump the #session# before line 400 and see do you get to see variables you are looking for, if yes – you can dump #kakapoBox.session# after line 406 – and check if Kakapo cached that correctly. you can mail me directly at sam@cflove.org with the results.

Monday 14 May 2012 11:26 AM
Just doing a follow up. Do you think it's too hard to change that? If you can point me around which line the "capture" is make, I can do some tests to let you know what to fix.

Friday 04 May 2012 11:34 AM
That’s defiantly helpful.

Friday 04 May 2012 11:26 AM
Maybe a USEFUL information for you. The error comes from a structure that is created, and populated in a CFC. In a CFDUMP, the structure is identified to "component <name of the CFC>".

The CFC is call with:
session.thisVar = createObject("component","xxx.xxx.xxx");

And inside the CFC, each variable is created with "this.variable1"

Friday 27 April 2012 12:12 PM
Hi Daniel,
I was not able to recreate the situation. but i will give another try this weekend.

Friday 27 April 2012 11:10 AM
Did you find anything? Maybe you can help me point where the data is "capture" so I can help you test and fix this.

Friday 13 April 2012 07:12 PM
Hi Sam, I'm using CF 9.0.1 on Windows 2008.

Friday 23 March 2012 03:01 PM
A small suggestion to the admin page: begin able to "Delete record(s)" directly from the summary section. It could really speeding up the process to delete entry that are resolved.

By the was, I've been able to use this using a different directory layout, using one admin for 3 websites, and using it as a CFINCLUDE inside a CFTRY block, or in a CFERROR, all with success. :-)
Tuesday 10 January 2012 10:22 AM
Hi JC, Sorry about that. This cause by update to the unsubscribe URL, old unsubscribe URL’s stop working. I unsubscribe your previous posts manually.
Sunday 01 January 2012 02:26 PM
Would you *please* fix your blog's unsubscribe functionality? I've been trying to unsubscribe from this post for a couple of months now and it hasn't worked yet. Neither does the email address that the comment notifications come from.
Friday 23 December 2011 02:41 AM
I have 2 questions:

1 --- how do I use Kakapo with Application.cfc that's all in cfscript? I do not believe there is a script version of

2 --- has anyone integrated this within Coldbox? I am having trouble knowing where to inject Kakapo in a Coldbox app.

Dan O'Keefe
Saturday 17 March 2012 09:42 AM
Were you able to integrate into Coldbox?
Tuesday 10 January 2012 10:13 AM
Hi Andy,
Sorry for the delay.
1. At this point only workaround is jump to tag view in the application.cfc/cfm file just for OnRequestStart()
2. I know some have used this with ColdBox, but not using ColdBox myself I’m not sure is there anything special with the Application.cfc file in ColdBox.
Monday 19 December 2011 01:37 PM
Hello Sam,
I can not see the snapshots of the errors. This is a screenshot: http://localhostr.com/file/irltcwy/cferror.png
I use CF9 Windows 2008 (IIS 7).

Wednesday 21 December 2011 01:30 PM
Open Kakapo/logs/pages and variables folders. it should have encrypted log files.
If those files were not created, open kakapo.cfm and check line 10 (kakapo.LogFolder) variable set correctly and also administrator/settings.cfm line 10 same variables. Also check those folders have read/write permission. Please let me know the progress, if that's a bug i can fix it.
Saturday 31 December 2011 09:39 AM
I tried to reinstall the script (in a new folder).

The situation does not change. The snapshots are not visible. I thought it was a problem of browser, but it is not true. I saw that even I do not receive e-mails with errors. First to receiving.

It can be a problem of configuration logs of coldfusion?

Happy new year!

Wednesday 21 December 2011 02:27 PM
I have checked.

1) the log file is encrypted;
2) the file path in the two files (administrator/settings.cfm and kakapo.cfm) is correct: C:\inetpub\localsite.it\classes\kakapo\logs
3) I have checked the permissions again. Are correct.

It can be a problem with coldfusion server configuration (configuration of logs)?

Saturday 19 November 2011 08:47 AM
Hello Sam,

thank you for suggestion, but this solution is not really suitable. First my concern is related to fact that Railo error handler (at least in this way is working) like just <cftry></cftry>, so it shows content generated before error occurred, not like cf error handler or kakapo (when its embedded in standard way with <cferror>).
The second issue - even if kakapo catches error (creates record into 'kakapo' table) it is not showing any error log in kakapo admin area, just header and blank screen. When I'm looked into DB I saw a new record which notify about new error - "Component [projects.bslfproject.Application] has no acessible Member with name [VIEWED]" (the same message I seeing if I'm switching back to standard error template and trying to look kakapo admin area).


Upd.: Before sending this post I decided to check the nature of second issue (not planned to dig deeper to save a time, but it appears not so difficult issue). You named queries just "this" in
"kakapo\administrator\bin\dsp_list.cfm" and "kakapo\administrator\bin\dsp_incidence.cfm"
but it looks like Railo is giving ability to access application.this scope even in this places and just searched for fields "viewed" and etc as methods of application scope. So I was forced to rename these queries (and corresponding references to query fields) to "thisQry" and it start working just fine.
Hope that helps.
Saturday 19 November 2011 04:47 PM
Hi Alex, good finding. For some reason im my server Railo let me used [this] without giving any issues. I will fix that.
Wednesday 16 November 2011 11:41 AM
Hello Sam,

Not so long ago I was forced to switch newly created site from CF9 to Railo by request of my client and I'm faced with follow issue - I found out that I'm not able to use <cferror type="exception" template="..."> tag within onRequestStart function in case if application.cfc also contains onRequest function. Only <cferror type="request" template="...">
which as I understand is not acceptable for Kakapo integration. I also can't delete onRequest function since it uses by site
logic. All of this perfectly working in CF9, but not Railo.
As I understand you tested Kakapo integration with Railo too.
Any advice?

Thursday 17 November 2011 03:14 PM
Also glad to let you know Todd Rafferty, Railo Community Manager (http://web-rat.com) also looking into this issue. So we may able to see what cause this.
Tuesday 10 January 2012 10:10 AM
Hi Alex, https://issues.jboss.org/browse/RAILO-1624 seems still open :(

Monday 09 January 2012 04:13 PM
Hello Sam, any updates?

Tuesday 06 December 2011 02:02 AM
Hello Sam,

How is it going? Had a chance to look at this issue? Any updates from Todd Rafferty?

Saturday 19 November 2011 08:49 AM
Glad to know about that, hope Todd will be able to help us to solve this issue.

Thursday 17 November 2011 01:46 PM
A workaround for this would be, set the kakapo.cfm file as the Railo site wide error handler. You can move the file into [web site path]\WEB-INF\railo\context\templates\error\kakapo.cfm and set [/railo-context/templates/error/kakapo.cfm] as the general error template (500) under the Railo Web Administrator > Settings > Error.

Still exploring what cause Railo to behave bit differently.
Wednesday 16 November 2011 12:00 PM
Can you move the <cferror type="exception" template="kakapo/kakapo.cfm"> to your existing onRequestStart() function?
Wednesday 16 November 2011 01:24 PM
Thanks Sam,
Will be waiting for your reply.


P.S. I also ask this question at
Railo Google group (http://groups.google.com/group/railo/browse_thread/thread/9548422cb43e681f),
but still have no any reply.

Wednesday 16 November 2011 12:54 PM
Thanks Alex, I will have a look and get back to you.

Wednesday 16 November 2011 12:35 PM
Hi Sam,

sorry if I may be described this not enough clear...

My <cferror type="exception" template="kakapo/kakapo.cfm"> is placed exactly into my existing onRequestStart().

It is working just fine if I commented out onRequest() function, but if onRequest() is also using (along with onRequestStart()) then <cferror> just not firing kakapo and I see standard Railo exception handler screen.

You can test it pretty easy as me, just create three files:
* application.cfc (add there just two functions - onRequest() and onRequestStart() and place <cferror type="exception" template="error.cfm"> tag to onRequestStart())
* error.cfm - just test error handling file (for example with test message "This is an error")
* index.cfm - with test error code (for example <cfset x = y> (there y is not defined before))
and just run. you will see what I mean.


Thursday 29 September 2011 04:16 PM
Hey there! It says that "Notifies You
Kakapo will email you when every time an error occurred in your application." -- is there an option to have it only email you for the first instance of an error, maybe have a timer after that and notify you every x minutes with a list of the times the same error has occurred, and reset after it hasn't happened for y minutes? The reason I'm looking for an exception manager app is to get rid of the tens of thousands of emails that get sent when an error happens.
Thursday 29 September 2011 10:18 PM
Hello Jc,
It does send an email on every occurrence of an error. If you want an email to be send out only on new errors, replace
line 330 in Kakapo.cfm :
<cfif len(kakapo.MailTo)>
<cfif len(kakapo.MailTo) and StructKeyExists(kakapo.i,'errorid') and not val(kakapo.i.errorid)>

That will do the trick. Yes. I should add that as an option.
Thursday 22 September 2011 08:37 PM
Very nice script. Thanks for sharing!
A good addition to this would be to get the entire cookie metadata array using getPageContext().getRequest().getCookies() and append it to the debugging output.
Sunday 28 August 2011 01:55 PM
Looks very useful.

Im new to coldfusion, so please excuse my lack of knowledge :-)

The install went fine.

I know need to add the lines to my application.cfc

ok, here's where i show how new I am. :-)

My application.cfc is all script. no tags.

how do i add the required code using just cfScript.

thanks for the help.

I think this is going to be very useful as Im learning to use coldfusion. there's going to be plenty of errors im sure :-)

Sunday 21 August 2011 11:24 AM
Hi Sam,

Tabs were not displaying for me due to #kakapo.LogFolder#/variables/#thisE.Code#.cfm file not exists.

Where can I get variables & pages folder ?

Thanks in advance.
Sunday 21 August 2011 12:05 PM
1. check [kakapo/logs/pages] and [kakapo/logs/variables] folders exists
2. Open [kakapo/Kakapo.cfm] file and check line 10, variable [kakapo.LogFolder] set to the [logs] folder. (eg: E:\iis\cflove.org\kakapo\logs)
3. Open [kakapo/administrator/settings.cfm] and check line 10, the above variable set to same folder (both should have the same value)

Also test:
Generate an Error, and see if new files been created in [variables] and [pages] folder.

Please let me know what happened.
Sunday 10 July 2011 05:53 AM
Hi Sam,
sorry, wasn't able to reply last days.
Thank you for the update.
Tuesday 05 July 2011 08:47 AM
Hello Sam,

Really great product, thank you. But I have some strange issue with it. When I'm trying to open "settings" it shows broken content. So, no "continue" button (as at example page), after last input from the example ("Description of the Custom Error Message ") I see the follow:

Above Blank space reserved for future use.
Fix Settings - Edit With Care

and etc.
Thursday 07 July 2011 04:26 PM
Hi Alex,
Sound like your [Custom Error Message] may have broke my code. If you can let me know the exact message, that would be really helpful. You can find that inside Kakapo.cfc file.
Saturday 09 July 2011 07:38 PM
Fixed that bug and new update released.
Friday 24 June 2011 11:03 AM

Does it work accross multiple servers (ie. could I get multiple different servers to update 1 database?)

Could I distinguish between development, test and production errors? or could I distinguish between the servers it is installed on?

How is the performance maintained? (is the sql efficient?)

Friday 24 June 2011 01:19 PM
Hi Joel, -
This is not the [enterprise] version. I’m working on multi server version now.
- No. But you can provide “Debug/development” IP address list and those IP addresses will receive robust error message instead friendly error message. it’s quite easy to store error IP into the database and sort/flag by that.
- Error snapshot use single table and single insert query. But at OnError(), this collect all variables (except formatted XML) in all main scopes, save into a wddx file. If you have a query returning one million records in the error page, this will try to take a snapshot of it and save it.
Wednesday 11 May 2011 08:18 AM
I love your posted content.
Dan O'Keefe
Monday 11 April 2011 10:30 AM
Can this be integrated into a model-glue application do you know?
Monday 11 April 2011 12:21 PM
I didn’t try Kakapo with Model-Glue, but since frameworks could not overwrite Application.cfm/cfc, it should works. Kakapo connects directly to application.cfm/cfc.
But you may want to block Model-Glue/framework variables been stored with error details.
Kakapo.cfc have [ignore variable] flag (line 59), by adding variable name to that, you can stop them been storied alone side with other more useful information. For example, fusebox use a variable “fb_” and already in the "ignore list".
Saturday 05 February 2011 03:33 PM
That’s great Ed!
Mail the zip to sam@cflove – org. I will add that. Need to open up a SVN now.
Saturday 05 February 2011 02:10 PM
I have made the updates to allow kakapo to be used via a cfinclude. I would like send you the changes so you can add it to the next version. is there an SVN repo i can commit to to or create a patch from or would you like me to zip up my install and send it..
Stewart McGuire
Friday 28 January 2011 10:16 AM
Is this compatible with BlueDragon? Commerical or OpenSource version(s)?
Friday 28 January 2011 10:21 AM
Unfortunately I haven’t got chance to test this with BlueDragon.
Tuesday 25 January 2011 11:43 PM
does this have the ability to be called inside a CFcatch so it can be used to log errors an app might need to hide (ajax apps)?
Wednesday 26 January 2011 05:55 PM
I think with bit of modification, kakapo.cfm file can be made to user as an ‘include’. But current version cannot do that.
Ed Lamp
Tuesday 25 January 2011 11:39 PM
very nice. for those that use this with fusebox. add "fb_" to the list of ignore variables. if you don't it screws up the saving of the variables log file.
Todd Mathews
Monday 24 January 2011 04:06 PM
Great job on this awesome app. It's a valuable solution and also demonstrates using a lot of the cool features in CF in a real world scenario.
Dan O'Keefe
Saturday 25 December 2010 07:47 PM
Saman, Very nice. I am going to check this out this weekend. Does it also override error handlers configured in CFAdmin?
Saturday 25 December 2010 08:06 PM
Yes. This technically has no connection to cfadmin settings. To the development IP address list, it display the full error message, and friendly error messages to the public. Let me know if you found any issues.