Types of errors

When you develop and run applications, you encounter different types of errors and error terminology. The following list introduces the major error types and terms:

Compile-time errors are raised by the ActionScript compiler during code compilation. Compile-time errors occur when syntactical problems in your code prevent your application from being built.

Run-time errors occur when you run your application after you compile it. Run-time errors represent errors that are caused while a SWF file plays in Adobe Flash Player 9. In most cases, you will be able to handle run-time errors as they occur, reporting them to the user and taking steps to keep your application running. If the error is a fatal error, such as not being able to connect to a remote website or load required data, you can use error handling to allow your application to finish gracefully.

Synchronous errors are run-time errors that occur at the time a function is invoked--for example, when you try to use a specific method and the argument you pass to the method is invalid, so Flash Player throws an exception. Most errors occur synchronously--at the time the statement executes--and the flow of control passes immediately to the most applicable catch statement.

For example, the following code excerpt throws a run-time error because the browse() method is not called before the program attempts to upload a file:

var fileRef:FileReference = new FileReference();
try
{
    fileRef.upload("http://www.yourdomain.com/fileupload.cfm");
}
catch (error:IllegalOperationError)
{
    trace(error);
    // Error #2037: Functions called in incorrect sequence, or earlier
    // call was unsuccessful.
}

In this case, a run-time error is thrown synchronously because Flash Player determined that the browse() method was not called before the file upload was attempted.

For detailed information on synchronous error handling, see Handling synchronous errors in an application.

Asynchronous errors are run-time errors that occur at various points during run time; they generate events and are caught by event listeners. An asynchronous operation is one in which a function initiates an operation, but doesn't wait for it to complete. You can create an error event listener to wait for the application or user to try some operation, and if the operation fails, you catch the error with an event listener and respond to the error event. Then, the event listener calls an event handler function to respond to the error event in a useful manner. For example, the event handler could launch a dialog box that prompts the user to resolve the error.

Consider the file-upload synchronous error example presented earlier. If you successfully call the browse() method before beginning a file upload, Flash Player would dispatch several events. For example, when an upload starts, the open event is dispatched. When the file upload operation completes successfully, the complete event is dispatched. Because event handling is asynchronous (that is, it does not occur at specific, known, predesignated times), you need to use the addEventListener() method to listen for these specific events, as the following code shows:

var fileRef:FileReference = new FileReference();
fileRef.addEventListener(Event.SELECT, selectHandler);
fileRef.addEventListener(Event.OPEN, openHandler);
fileRef.addEventListener(Event.COMPLETE, completeHandler);
fileRef.browse();

function selectHandler(event:Event):void
{
    trace("...select...");
    var request:URLRequest = new URLRequest("http://www.yourdomain.com/fileupload.cfm");
    request.method = URLRequestMethod.POST;
    event.target.upload(request.url);
}
function openHandler(event:Event):void
{
    trace("...open...");
}
function completeHandler(event:Event):void
{
    trace("...complete...");
}

For detailed information on asynchronous error handling, see Responding to error events and status.

Uncaught exceptions are errors thrown with no corresponding logic (like a catch statement) to respond to them. If your application throws an error, and no appropriate catch statement or event handler can be found at the current or higher level to handle the error, the error is considered an uncaught exception.

At run time, Flash Player ignores, by design, uncaught errors and tries to continue playing if the error doesn't stop the current SWF file, because users can't necessarily resolve an error themselves. The process of ignoring an uncaught error is called "failing silently" and can complicate debugging applications. The debugger version of Flash Player responds to an uncaught error by terminating the current script and displaying the uncaught error in trace statement output or writing the error message to a log file. If the exception object is an instance of the Error class or one of its subclasses, the getStackTrace() method is invoked, and the stack trace information will also be displayed in trace statement output or in a log file. For more information about using the debugger version of Flash Player, see Working with the debugger version of Flash Player.