Causes the specified function to be called automatically when an unhandled error occurs.

OnError Function , AddRemove



Type: Function Object

The function object to call when an unhandled error occurs. The function's parameters and return value are described below.


Type: Integer

If blank or omitted, it defaults to 1 (call the function after any previously registered functions). Otherwise, specify one of the following numbers:


The function should accept two parameters:

FunctionName(Thrown, Mode)

Type: Any

The thrown value, usually an Error object.


Type: String

One of the following strings:

Return Value

The callback function can return one of the following values (other values are reserved for future use and should be avoided):


Function is called only for errors or exceptions which would normally cause an error message to be displayed. It cannot be called for a load-time error, since OnError cannot be called until after the script has loaded.

Function is called on the current thread, before it exits (that is, before the call stack unwinds).

Try, Catch, Throw, OnExit


Logs errors caused by the script into a text file instead of displaying them to the user.

OnError LogError
i := Integer("cause_error")

LogError(exception, mode) {
    FileAppend "Error on line " exception.Line ": " exception.Message "`n"
        , "errorlog.txt"
    return true

Use OnError to implement alternative error handling methods. Caveat: OnError is ineffective while Try is active.

    local ea := ErrorAccumulator()
    return ea

class ErrorAccumulator
    Errors := []                        ; Array for accumulated errors.
    _cb := AccumulateError.Bind(this.Errors)
    Start() => OnError(this._cb, -1)    ; Register our cb before others.
    Stop() => OnError(this._cb, 0)      ; Unregister our cb.
    Last => this.Errors[-1]             ; Most recent error.
    Count => this.Errors.Length         ; Number of accumulated errors.
    __item[i] => this.Errors[i]         ; Shortcut for indexing.
    __delete() => this.Stop()           ; For tying to function scope.

; This is the OnError callback function. 'errors' is given a value via Bind().
AccumulateError(errors, e, mode)
    if mode != "Return" ; Not continuable.
    if e.What = "" ; Expression defect or similar, not a built-in function.
    try {
        ; Try to print the error to stdout.
        FileAppend Format("{1} ({2}) : ({3}) {4}`n", e.File, e.Line, e.What, e.Message), "*"
        if HasProp(e, "extra")
            FileAppend "     Specifically: " e.Extra "`n", "*"
    return -1 ; Continue.

    ; Start accumulating errors in 'err'.
    local err := AccumulateErrors()

    ; Do some things that might fail...
    MonitorGetWorkArea , &left, &top, &right, &bottom
    width := (right-left)//2, height := bottom-top
    WinMove left, top, width, height, A_ScriptFullPath
    WinMove left+width, top, width, height, "AutoHotkey v2 Help"

    ; Check if any errors occurred.
    if err.Count
        MsgBox err.Count " error(s); last error at line #" err.Last.Line
        MsgBox "No errors"

    ; Stop is called automatically when the variable goes out of scope,
    ; since only we have a reference to the object.  This causes OnError
    ; to be called to unregister the callback.

; Call the test function which suppresses and accumulates errors.
; Call another function to show normal error behaviour is restored.
WinMove 0, 0, 0, 0, "non-existent window"