Exception Handling MDCFUG 6/12/2007 David Lakein Programmer / Analyst TeraTech Inc.

About Me Application Developer at TeraTech since 1998 Working in ColdFusion since 1999, CF4.01 Certified Advanced CF7 Developer

What’s wrong with this picture?

The Problem Too much info gets shown to users –Embarrassing –Could be security hazard Site admins/developers need notification, enough useful debugging info to find the error and be able to fix –Users won’t send it to you, and you don’t want them seeing it anyway!

What this presentation will cover Different types of errors Language features used to catch and handle –Overview of properties –Suggestions for usage Creating a simple customizable general error handler

What this will not cover Won’t cover all details and properties of cfcatch and error object Check out the references at the end

Types of errors Exception: Error that doesn’t allow the request to continue. –You can catch the error, and CF gives you a structure with error details. Types/examples of errors: –Parse/Compile error: malformed CF tags –Syntax error: missing property –Runtime: won’t be found until code executes –Validation: server-side form validation –System: connection fails –Request: URL that user requested doesn’t exist Not a CF exception, but CF can handle Different from CF’s CFError type=Request –Logic errors: don’t directly cause an exception, but are still wrong

Error: Parse ColdFusion first parses the templates, then compiles into Java. If CF cannot parse the syntax, there is little useful it can do with it. If it’s in the main request page, won’t be caught by CFCatch, CFError, or OnError! –Goes straight to server-wide error handler –Will be caught properly if parse error happens in an include (lower level than the error handler) I have no closing cfif tag.

Error: Syntax Code can be parsed, but language use is wrong, which may prevent it from being compiled. e.g., Missing required attributes or arguments, invalid parameters CF will say: "Unknown tag: cfbad. ColdFusion cannot determine how to process the tag cfbad because the tag is unknown and not in any imported tag libraries. The tag name might be misspelled…"

Error: Runtime Errors that happen when the code is executing This covers most other kinds of code errors –Error responses from outside CF CFHTTP calls Database –CFML errors Undefined variables CFThrow creating a custom exception type CFAbort with “showerror” attribute E.g., Value set in in a variable at runtime is the wrong type for a function argument, if it has a type.

Error: Validation CF has basic built-in server-side form validation fields; e.g., hidden fields named “fieldname_required” or “fieldname_type”. If the submitted data fails, CF throws a Validation error. Similar feature will be generated by CF7's CFInput validateAt="onServer" Depends on the extra hidden form fields submitted by client

Error: System Type of runtime error Bad connection to db File is missing

Reducing Details Shown By Default Turn off Robust Exception Information to reduce what gets shown to the user if an error isn’t handled, or if the exception handler fails.

Where CF Handles Errors Server-wide error handler Server-wide missing template handler –HTTP 404 error CFError tag –Catches unhandled errors anywhere after the point where it is defined Application.cfc onError event (CF7+) Application.cfc onMissingTemplate event (CF8, in public beta) –Local HTTP 404 handler CFTry/CFCatch –Catch errors right around the code they happen

Server-wide error and 404 handlers Missing Template handler: URL from root of the website –HTTP 404 errors –Browser requests CF page that doesn’t exist; webserver passes to ColdFusion to handle. Site-wide error handler: ColdFusion path, including mappings, from root. –Template that is executed whenever an error is not handled at the application or code level.

CFError Catches unhandled errors anywhere after the point where it is defined Declare anywhere in cfm pages. Should be near the top of the Application.cfc or Application.cfm Object named “Error” – error details, stack trace, location, templates called

CFError (cont’d) Attributes: –Template: CF relative or absolute mapping path to the error handler template –Type –Exception (optional): specific type to catch –Mailto (optional): passes in as error.mailTo Type: –Type=“Exception” – full exception handler. –Type=“Request” – errors that fail exception handler. Limited; can only output Error variables. –Type=“Validation” – CF form validation. Limited like Request type.

CFError example sample.cfm Example: cferror in Application.cfm, mail to admin. #NonExistentVariable# Since we are using cferror type="Exception", html after the error will not appear, and html before the error will only show in Error.GeneratedContent. Application.cfm

CFError example (cont’d) Exception.cfm <cfmail server=“mailserver.domain.com" to="#mailto#" subject="Error in Example App on #CGI.HTTP_HOST#" type="html"> ERROR In page: #Error.Template# An error occurred. <div style="background-color: ##cc4400; padding: 1em; Sorry, there was an error. Site admins have been contacted.

CFError example (cont’d) What user sees: What admin gets:

Application.cfc onError event (CF 7+) Arguments: –Exception - exception object Similar in structure to the CFCatch object you get with cftry/cfcatch –EventName - string Contains Application event name, if error is in Application.cfc Otherwise, blank string No return value You can/should still have a cferror tag in the declarations section of your Application.cfc; that will run if there is an error in your OnError event. Overrides all other error handlers besides CFCatch Check limitations in LiveDocs; no output if runs in onApplicationEnd or onSessionEnd events

Application.cfc onError event Example Error caught in Application.cfc, #GetCurrentTemplatePath()# Event name: '#Arguments.EventName#' ---> <cfdump var="#Arguments.Exception#" label="#Arguments.EventName# Exception"> …

Application.cfc onMissingTemplate event (CF 8, beta) Used as a local application-specific 404 handler: when page specified in URL does not exist. Arguments: targetPage string. Return true if handled ok, false if you want to throw a 404 error. –If there is a Missing Template error handler defined in CFAdmin, that will catch. –If that is not defined, CF's built-in default 404 handler will run

Application.cfc onMissingTemplate event (CF 8, beta) example #Arguments.targetPage# could not be found. You requested a non-existent ColdFusion page. Please check the URL.

CFTry/CFCatch Wrap the CFTry/CFCatch around a block of code, and it handles errors inside that block Handles errors locally; can show inside the layout. Inside the cfcatch tags, you have an object named “cfcatch”, contains error properties and related objects. You can specify catching certain types only Rethrow error (tag CFRETHROW) if you want to send the error to a higher level.

CFTry/CFCatch sample <!--- any code out here will be handled by the above exception handler "exception.cfm", or by the Application.cfc OnError if it exists ---> <cfinclude template="test2.cfm" There was an error with this operation! <!--- any code out here will be handled by the above exception handler "exception.cfm", or by the Application.cfc OnError if it exists ---> <cfinclude template="test3.cfm"

What to do in your error handler Log –CF already logs basic exception info to exception.log –Could log extra error info to file, one line per error –New in CF8: there will be built-in Derby databases – all inside the CF service, no connections to go down. This may allow for logging other properties than would be doable in a text log, then provide for easy search capability. –HTML formatted , get a table of all the info you need Use a common template –Pass in settings for CFMail or logging. –Optionally show debug info for local developers – pass in Debug variable controlled by IP and a URL var CAUTION: if there is an error in this level, like DB connection, or malformed, will throw the original error to a higher level! –You won't know about the exception in the error handler.

What to send Scopes: error/cfcatch/exception object, cgi scope, form, other scopes Simple version: cfdump Server-wide handler: shouldn’t have a lot of moving parts. –If you check specific optional parts of the error/catch object, check StructKeyExists first! –If you have a more involved template, use try/catch in that, and do a basic action by default. Always handle.

CFDump You may want to write code to parse out the properties of the error/catch object, instead of just dumping. –Highlight most important/useful properties at the top of the –Potential issue with dumping a CFCatch: There may be an issue with dumping the full object, depending on server installation, version (6.1) –Error detail message may not be clear; also could include HTML content which you won’t want in there. –Process SQL output, show query more visibly.

Example 1: CFError included in same file err1.cfm : Example 1: Use cferror in the template #NonExistentVariable# Since we are using cferror type="Exception", html after the error will not appear, and html before the error will only show in Error.GeneratedContent.

Example 1 (cont’d) exception.cfm : Exception Template Example 1 Error scope: CGI scope: Error handled at: #GetCurrentTemplatePath()#

Example 2: CFError included in Application.cfm err2.cfm Example 2: Use cferror in the Application.cfm #NonExistentVariable# Since we are using cferror type="Exception", html after the error will not appear, and html before the error will only show in Error.GeneratedContent. Application.cfm

Example 2 (cont’d) exception.cfm Exception Template Example 2 Error scope: CGI scope: Error handled at: #GetCurrentTemplatePath()#

Example 3: onError event of Application.cfc (CF7+ only) Error caught in Application.cfc, #GetCurrentTemplatePath()# Event name: '#Arguments.EventName#' Application.cfc

Example 3 (cont’d) err3.cfm Example 3: Use OnError in the Application.cfc #NonExistentVariable# Since this error is caught by its Application.cfc OnError event, html after the error will not appear, BUT html before the error will output to the browser.

Example 4: onMissingTemplate event of Application.cfc (CF8 only, in beta) Application.cfc #Arguments.targetPage# could not be found. You requested a non-existent ColdFusion page. Please check the URL. <!--- If an error occurs, return false and the default 404 error handler will run. --->

Example 5a, CFTry/CFCatch File error Application.cfc, like in example 3 badfile.cfm Example 5: Try/catch, file error <!--- If you want to not handle this here, rethrow this error to the higher handler. ---> ---> Error handled at: #GetCurrentTemplatePath()#, CFCatch If there was no error in the Catch block, this should display.

Example 5b, CFTry/CFCatch DB error baddb.cfm Example 5: Try/catch - Database error Select bar FROM foo <!--- If you want to not handle this here, rethrow this error to the higher handler. ---> ---> Error handled at: #GetCurrentTemplatePath()#, CFCatch If there was no error in the Catch block, this should display. Application.cfc like in example 3

Example: CFError, break CFMail Exception.cfm (like the first CFError example).. <cfmail serRRRver=“mailserver.domain.com" to="#mailto#" subject="Error in Example App on #CGI.HTTP_HOST#" type="html">..... User sees original error:

Other useful info GetCurrentTemplatePath() – if you have error handling templates multiple places, shows exactly where this error template is. CGI. HTTP_HOST – Which site this is running on (in subject line) Other CGI info

Caveats If you have a high-volume site, you may want another solution than ing you every time, especially for errors that each and every visitor will hit. If you use CFParam and CFQueryParam on form or URL values: Make sure you handle form validation before this on the server-side. –Provides for nicer validation messages –Form value type errors won’t clutter your inbox, distracting from real errors.

References Livedocs –“Handling Errors” (chapter) –“How ColdFusion handles errors” –CFAdministrator Settings page: global 404 and exception handlers –Application.cfc OnError Quickdocs: – – Other presos –Mosh Teitelbaum, Feb 2004: Google search –“site:livedocs.adobe.com ColdFusion 7 keywords”