Whatever message this page gives is out now! Go check it out!
Understanding errors
Last update:
Jun 9, 2026
Note:
As of ColdFusion (2021 release), CORBA has been removed. You can no longer use CORBA-related features, functions, and tags.
You can look at errors in many ways; for example, you can look at errors by their causes. You can also look at them by their effects, particularly by whether your application can recover from them. You can also look at them the way ColdFusion does, as follows:
About error causes and recovery
Errors can have many causes. Depending on the cause, the error can be recoverable. A recoverable error is one for which your application can identify the error cause and take action on the problem. Some errors, such as time-out errors, are recoverable without indicating to the user that an error was encountered. An error for which a requested application page does not exist is not recoverable, and the application can only display an error message.
Errors such as validation errors, for which the application cannot continue processing the request, but can provide an error-specific response, can also be considered recoverable. For example, an error that occurs when a user enters text where a number is required can be considered recoverable, because the application can recognize the error and redisplay the data field with a message providing information about the cause of the error and telling the user to reenter the data.
Some types of errors are recoverable in some, but not all circumstances. For example, your application can retry a request following a time-out error, but it must also be prepared for the case where the request always times out.
Error causes fall in the broad categories listed in the following table:
Errors such as validation errors, for which the application cannot continue processing the request, but can provide an error-specific response, can also be considered recoverable. For example, an error that occurs when a user enters text where a number is required can be considered recoverable, because the application can recognize the error and redisplay the data field with a message providing information about the cause of the error and telling the user to reenter the data.
Some types of errors are recoverable in some, but not all circumstances. For example, your application can retry a request following a time-out error, but it must also be prepared for the case where the request always times out.
Error causes fall in the broad categories listed in the following table:
Category | Description |
Program errors | Can be in the code syntax or the program logic. The ColdFusion compiler identifies and reports program syntax errors when it compiles CFML into Java classes. Errors in your application logic are harder to locate. For information on debugging tools and techniques, see Debugging and Troubleshooting Applications.Unlike ColdFusion syntax errors, SQL syntax errors are only caught at runtime. |
Data errors | Are typically user data input errors. You use validation techniques to identify errors in user input data and enable the user to correct the errors. |
System errors | Can come from a variety of causes, including database system problems, time-outs due to excessive demands on your server, out-of-memory errors in the system, file errors, and disk errors. |
Although these categories do not map completely to the way ColdFusion categorizes errors they provide a useful way of thinking about errors and can help you in preventing and handling errors in your code.
ColdFusion error types
Before you can effectively manage ColdFusion errors, you must understand how ColdFusion classifies and handles them. ColdFusion categorizes errors as detailed in the following table:
Type | Description |
Exception | An error that prevents normal processing from continuing. All ColdFusion exceptions are, at their root, Java exceptions. |
Missing template | An HTTP request for a ColdFusion page that cannot be found. Generated if a browser requests a ColdFusion page that does not exist.Missing template errors are different from missing include exceptions, which result from cfinclude tags or custom tag calls that cannot find their targets. |
Form field data validation | Server-side form field validation errors are a special kind of ColdFusion exception. You specify server-side form validation by using cfform attributes or hidden HTML form fields. All other types of server-side validation, such as the cfparam tag generate runtime exceptions. For more information on validating form fields see Validating data.ColdFusion includes a built-in error page for server-side form field validation errors, and the cferror tag includes a type attribute that lets you handle these errors in a custom error page, but if you use onError processing in Application.cfc, or try/catch error handling, the error appears as an Application exception. For more information on handling Form field validation in Application. cfc see Handling server-side validation errors in the on Error method in Defining the application and its event handlers in Application.cfc. |
Note:
The onSubmit and onBlur form field validation techniques use JavaScript or Flash validation on the client browser.
About ColdFusion exceptions
Most ColdFusion errors are exceptions. You can categorize ColdFusion exceptions in two ways:
- When they occur
- Their type
When exceptions occur
ColdFusion errors can occur at two times, when the CFML is compiled into Java and when the resulting Java executes, called runtime exceptions.
Compiler exceptions
Compiler exceptions are programming errors that ColdFusion identifies when it compiles CFML into Java. Because compiler exceptions occur before the ColdFusion page is converted to executable code, you cannot handle them on the page that causes them. However, other pages can handle these errors. For more information, see Handling compiler exceptions in Determining error-handling strategies.
Runtime exception
A runtime exception occurs when the compiled ColdFusion Java code runs. It is an event that disrupts the normal flow of instructions in the application. Exceptions can result from system errors or program logic errors. Runtime exceptions include:
- Error responses from external services, such as an ODBC driver or CORBA server
- CFML errors or the results of cfthrow or cfabort tags
- Internal errors in ColdFusion
ColdFusion exception types
ColdFusion exceptions have types that you specify in the cferror , cfcatch , and cfthrow error-handling tags. A cferror or cfcatch tag handles only exceptions of the specified type. You identify an exception type by using an identifier from one (or more) of the following type categories:
- Basic
- Custom
- Advanced
- Java class
Note:
Use only custom error type names and the Application basic type name in cfthrow tags. All other built-in exception type names identify specific types of system-identified errors, so do not use them for errors that you identify yourself.
Basic exception types
All ColdFusion exceptions except for custom exceptions belong to a basic type category. These types consist of a broadly defined categorization of ColdFusion exceptions. The following table describes the basic exception types:
Type | Type name | Description |
Database failures | Database | Failed database operations, such as failed SQL statements, ODBC problems, and so on. |
Missing include file errors | MissingInclude | Errors where files specified by the cfinclude , cfmodule , and cferror tags are missing. (A cferror tag generates a missingInclude error only when an error of the type specified in the tag occurs.)The MissingInclude error type is a subcategory of Template error. If you do not specifically handle the MissingInclude error type, but do handle the Template error type, the Template error handler catches these errors. MissingInclude errors are caught at runtime. |
Template errors | Template | General application page errors, including invalid tag and attribute names. Most Template errors are caught at compile time, not runtime. |
Object exceptions | Object | Exceptions in ColdFusion code that works with objects. |
Security exceptions | Security | Catchable exceptions in ColdFusion code that works with security. |
Expression exceptions | Expression | Failed expression evaluations; for example, if you try to add 1 and "a". |
Locking exceptions | Lock | Failed locking operations, such as when a cflock critical section times out or fails at runtime. |
Application-defined exception events raised by cfthrow | Application | Custom exceptions generated by a cfthrow tag that do not specify a type, or specify the type as Application. |
All exceptions | Any | Any exceptions. Includes all types in this table and any exceptions that are not handled in another error handler, including unexpected internal and external errors. |
Note:
The Any type includes all error with the Java object type of java.lang.Exception. It does not include java.lang.Throwable errors. To catch Throwable errors, specify java.lang.Throwable in the cfcatch tag type attribute.
Custom exceptions
You can generate an exception with your own type by specifying a custom exception type name, for example MyCustomErrorType, in a cfthrow tag. You then specify the custom type name in a cfcatch or cferror tag to handle the exception. Custom type names must be different from any built-in type names, including basic types and Java exception classes.
Advanced exception types
The Advanced exceptions consist of a set of specific, narrow exception types. These types are supported in ColdFusion for backward-compatibility.
Java exception classes
Every ColdFusion exception belongs to, and is identified by, a specific Java exception class in addition to its basic, custom, or advanced type. The first line of the stack trace in the standard error output for an exception identifies the Java class of the exception.
For example, if you attempt to use an array function such as ArrayIsEmpty on an integer variable, ColdFusion generates an exception that belongs to the Expression exception basic type and the coldfusion .runtime.NonArrayException Java class.
In general, most applications do not use Java exception classes to identify exceptions. However, you can use Java class names to catch exceptions in non-CFML Java objects; for example, the following line catches all Java input/output exceptions:
For example, if you attempt to use an array function such as ArrayIsEmpty on an integer variable, ColdFusion generates an exception that belongs to the Expression exception basic type and the coldfusion .runtime.NonArrayException Java class.
In general, most applications do not use Java exception classes to identify exceptions. However, you can use Java class names to catch exceptions in non-CFML Java objects; for example, the following line catches all Java input/output exceptions:
<cfcatch type="java.io.IOException">How ColdFusion handles errors
The following information describes briefly how ColdFusion handles errors. Detailed information is provided in the remaining topics.
Missing template errors
If a user requests a page that ColdFusion cannot find, and the Administrator Server Settings Missing Template Handler field specifies a Missing Template Handler page, ColdFusion uses that page to display error information. Otherwise, it displays a standard error message.
Form field validation errors
When a user enters invalid data in an HTML tag that uses onServer or hidden form field server-side data validation ColdFusion does the following:
- If the Application CFC (Application.cfc) has an onError event handler method, ColdFusion calls the method.
- If the Application.cfc initialization code or the Application.cfm page has a cferror that specifies a Validation error handler, ColdFusion displays the specified error page.
- Otherwise, it displays the error information in a standard format that consists of a default header, a bulleted list describing the errors, and a default footer.For more information on using hidden form field validation, see Validating data. For more information on Application.cfc, see Designing and Optimizing a ColdFusion Application.
Compiler exception errors
If ColdFusion encounters a compiler exception, how it handles the exception depends on whether the error occurs on a requested page or on an included page:
- If the error occurs on a page that is accessed by a cfinclude or cfmessagebox cfmodule tag, or on a custom tag page that you access using the cf_ notation, ColdFusion handles it as a runtime exception in the page that accesses the tag. For a description of how these errors are handled, see the next section, " Runtime exception errors."
- If the error occurs directly on the requested page, and the Administrator Settings Site-wide Error Handler field specifies an error handler page, ColdFusion displays the specified error page. Otherwise, ColdFusion reports the error using the standard error message format described in Error messages and the standard error format.
Runtime exception errors
If ColdFusion encounters a runtime exception, it does the action for the first matching condition in the following table:
Condition | Action |
The code with the error is inside a cftry tag and the exception type is specified in a cfcatch tag. | |
The ColdFusion application has an Application.cfc with an onError method | Executes the code in the onError method. For more information on using the onError method, see Handling errors in Application.cfc in Defining the application and its event handlers in Application.cfc. |
A cferror tag specifies an exception error handler for the exception type. | Uses the error page specified by the cferror tag. |
The Administrator Settings Site-wide Error Handler field specifies an error handler page. | Uses the custom error page specified by the Administrator setting. |
A cferror tag specifies a Request error handler. | Uses the error page specified by the cferror tag. |
The default case. | Uses the standard error message format |
For example, if an exception occurs in CFML code that is not in a cftry block, and Application.cfc does not have an onError method, but a cferror tag specifies a page to handle this error type, ColdFusion uses the specified error page.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
