Understanding errors

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:

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:

<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:

  1. If the Application CFC (Application.cfc) has  an  onError  event handler method, ColdFusion calls the method.

  2. 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.

  3. 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.

Executes the code in the cfcatch tag.If the cftry block does not have a cfcatch tag for this error, tests for an appropriate cferror handler or site-wide error handler.

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.

Adobe logo

Sign in to your account