ColdFusion provides you with many options for handling errors, particularly exceptions, as described in How ColdFusion handles errors in Understanding errors. The considerations for determining which forms of error handling to use are as follows:
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> |
(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, to give the error message a custom look or provide additional information such as service contact phone numbers and addresses, use the cferror tag with the Validation attribute in the Application.cfc initialization code. Or, specify your own validation on the Application.cfm page. An example of such a page is provided at Example of a validation error page section. You can also place 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. 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 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, 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 |
|---|---|
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 does 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 are generated by multiple code sections in the application. For more information on error handling using Application.cfc, see Handling errors in Application.cfc in Understanding errors. |
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 cause of the error and the steps to 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. Place 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 section. |
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. |
