.AS File Format – Errors and exceptions

throw

throw expression;

Any value can be thrown, but code normally throws an instance of Error or a subclass, which carries a message and a stack trace.

if (index < 0 || index >= items.length) {
    throw new RangeError("Index " + index + " is out of range");
}

try, catch and finally

try {
    statements
} catch (name:ErrorType) {
    statements
} [catch (name:OtherType) { … }]…
[finally {
    statements
}]

• A try needs at least one catch or a finally.
• Each catch names a variable and, optionally, a type. The first clause whose type matches the thrown value runs; the rest are skipped. List the most specific types first and Error last.
• A catch without a type, or typed *, catches anything.
• When no clause matches, the exception goes on to the caller.
• finally runs whether the block finished, threw or returned.

try {
    var data:Object = JSON.parse(text);
    bytes.readUnsignedInt();
} catch (e:SyntaxError) {
    trace("not JSON:", e.message);
} catch (e:EOFError) {
    trace("ran out of data");
} catch (e:Error) {
    trace("other error", e.errorID, e.message);
} finally {
    bytes.position = 0;
}

The Error class

package com.example {
    public class ParseError extends Error {
        public var line:int;

        public function ParseError(message:String, line:int) {
            super(message);
            name = "ParseError";
            this.line = line;
        }
    }
}

Built-in error classes

Error events

Loading, networking and other work that completes later cannot throw into the code that started it. It dispatches an event instead, and a listener handles it. An error event with no listener becomes an uncaught error.

var loader:URLLoader = new URLLoader();
loader.addEventListener(Event.COMPLETE, onLoaded);
loader.addEventListener(IOErrorEvent.IO_ERROR, onFailed);
loader.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onFailed);
loader.load(new URLRequest("data.json"));

loaderInfo.uncaughtErrorEvents.addEventListener(
    UncaughtErrorEvent.UNCAUGHT_ERROR,
    function (e:UncaughtErrorEvent):void {
        e.preventDefault();          // stop the debugger dialog
        trace("uncaught:", e.error);
    });

A debug player shows a dialog for every uncaught error; release players show nothing and carry on with the next event.

Common run-time errors

Adobe’s reference lists every run-time error and compiler error by number.