Determining error-handling strategies

ColdFusion provides you with many options for handling errors, particularly exceptions, as described in the section How ColdFusion handles errors. This section describes considerations for determining which forms of error handling to use.

Handling missing template errors

Missing template errors occur when ColdFusion receives an HTTP request for a page ending in .cfm that it cannot find. You can create your own missing template error page to present application-specific information or provide an application-specific appearance. You specify the missing template error page on the Administrator Settings page.

The missing error page can use CFML tags and variables. In particular, you can use the CGI.script_name variable in text such as the following to identify the requested page:

<cfoutput>The page #Replace(CGI.script_name, "/", "")# is not available.<br>
Make sure that you entered the page correctly.<br>
</cfoutput>

(In this code, the Replace function removes the leading slash sign from the script name to make the display more friendly.)

Handling form field validation errors

When you use server-side form field validation, the default validation error message describes the error cause plainly and clearly. However, you might want to give the error message a custom look or provide additional information such as service contact phone numbers and addresses. In this case, use the cferror tag with the Validation attribute in the Application.cfc initialization code or on the Application.cfm page to specify your own validation error handler. The section Example of a validation error page provides an example of such a page. You can also put form field validation error handling code in the Application.cfc onError method.

Handling compiler exceptions

You cannot handle compiler exceptions directly on the page where they occur, because the exception is caught before ColdFusion starts running the page code. You should fix all compiler exceptions as part of the development process. Use the reported error message and the code debugging techniques discussed in Debugging and Troubleshooting Applications to identify and correct the cause of the error.

Compiler exceptions that occur on pages you access by using the cfinclude or cfmodule tags can actually be handled as runtime errors by surrounding the cfinclude or cfmodule tag in a cftry block. The compiler exception on the accessed page gets caught as a runtime error on the base page. However, you should avoid this "solution" to the problem, as the correct method for handling compiler errors is to remove them before you deploy the application.

Handling runtime exceptions

You have many choices for handling exceptions, and the exact path you take depends on your application and its needs. The following table provides a guide to selecting an appropriate technique:

Technique	Use
`cftry`	Place `cftry` blocks around specific code sections where exceptions can be expected and you want to handle those exceptions in a context-specific manner; for example, if you want to display an error message that is specific to that code. Use `cftry` blocks where you can recover from an exception. For example, you can retry an operation that times out, or access an alternate resource. You can also use the `cftry` tag to continue processing where a specific exception will not harm your application; for example, if a missing resource is not required. For more information, see Handling runtime exceptions with ColdFusion tags.
Application.cfc `onError` method	Implement the `onError` method in your Application.cfc to consistently handle application-specific exceptions that might be generated by multiple code sections in the application. For more information on error handling using Application.cfc, see Handling errors in Application.cfc.
`cferror` `with` exception- specific error handler pages	Use the `cferror` tag to specify error pages for specific exception types. These pages cannot recover from errors, but they can provide the user with information about the error's cause and steps that they can take to prevent the problem. For more information, see Specifying custom error messages with the cferror tag.
`cferror` with a Request error page	Use the `cferror` tag to specify a Request error handler that provides a customized, application-specific message for unrecoverable exceptions. Put the tag in the Application.cfc initialization code or on the Application.cfm page to make it apply to all pages in an application. A Request error page cannot use CFML tags, but it can display error variables. As a result, you can use it to display common error information, but you cannot provide error-specific instructions. Typically, Request pages display error variable values and application-specific information, including support contact information. For example code, see Example of a request error page.
Site-wide error handler page	Specify a site-wide error handler in the Administrator to provide consistent appearance and contents for all otherwise-unhandled exceptions in all applications on your server. Like the Request page, the site-wide error handler cannot perform error recovery. However, it can include CFML tags in addition to the error variables. Because a site-wide error handler prevents ColdFusion from displaying the default error message, it allows you to limit the information reported to users. It also lets you provide all users with default contact information or other instructions.

View comments in LiveDocs