Mura Basics: Debugging and Reporting Errors
October 27, 2015 by Michael Evangelista
In any development cycle there is a certain amount of trial and error. Even the most experienced developers make incorrect assumptions, forget crucial elements, or type too quickly.
Anyone doing web development or editing code is bound to run into obstacles sooner than later, with error messages that may be both frequent and somewhat cryptic. Understanding and becoming familiar with the contents of these on-screen errors is one of the best ways to boost confidence and limit frustration.
The first step in troubleshooting or asking for help with a server error is to gather all of the relevant information possible. If the message on the screen includes any details other than a generic error code, this information should be selected and copied to the viewer's clipboard, or captured in a screen shot, where it can be pasted into an email, forum post, support ticket or other communication. It is also useful to note the events or actions leading up to the error event, including any requirements for login or steps to recreate the error - a professional support technician or developer will almost always ask these questions right up front.
Showing CFML Error Details
Sometimes the error message shown is so simple as to be practically useless. For example, some servers will catch the error response from a .cfm page and wrap it in a default 500-code error message, showing only the most basic text on the screen.
In a Windows / IIS server environment, this line can be added to the site's web.config file, inside the <system.webServer> block, to prevent CF error details from being blocked by the web server:
<httpErrors existingResponse="PassThrough" />
This instructs the web server to refrain from masking the errors with generic codes, including the common 500' error message, allowing the actual CFML error response "pass through" and be shown on the screen.
In addition, all of the major CFML engines have options for enabling detailed exception information or making changes to the error handling template, which will enable the showing of crucial details such as file name and location, line number, and the stack trace of includes, methods and operations leading to the actual line with the error. While not intended for use in production, this is an invaluable aid when attempting to track down a problem, and can be easily toggled back to the 'off' or public state once the issue is resolved.
A similar output can be seen without adjusting server-side settings, using the robust <cftry> and <cfcatch> tags (or a try/catch block in cfscript). By wrapping suspect code in 'cftry' and dumping out the contents of 'cfcatch' on any error, the full stack of cfml error details will be shown on the screen. Mura uses this approach at multiple key points in the core code, to handle errors which may otherwise be hard to track down.
Of course, the server's log files can also be a relevant source of information, but for basic troubleshooting or fixing problems created by code edits, viewing the full range of information right on the screen is a good tool to be familiar with.
Debugging in the Browser
All modern web browsers include a robust set of tools for inspecting and debugging the contents of a web page, along with a wealth of details about each request, asset or transaction associated with the page view. (In most cases, a handy keyboard shortcut will launch the developer tools or web inspector window.) Regardless of browser preference, the debugging resources available in the debugging options are crucial components for a professional workflow.
Additionally, the browser's 'network' options will show the response from the server along with an option to preview the results of the failed operation as if browsing the remote page directly. With CFML error reporting enabled, this can be a most useful tool for finding and fixing the problem, starting directly in the web browser.
When error details alone don't provide enough information, any request for assistance should include at least some type of error details, along with a basic description of the problem. The more information gathered and reported, the more likely a solution is to be found.
What may appear as undecipherable code to one person might be exactly what another needs to suggest or apply a solution. Collecting all of the available information - via CFML error details, cftry/cfcatch handling and/or the browser's error detail reporting options - will expedite any attempt to find a problem, and apply a successful fix.
More About Mura
Also see: Mura Basics - Getting Help getmura.com/blog/mura-basics-getting-help