Class

# RuntimeException

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

An error occurring at runtime.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                        | Type                               | Read-Only | Shared |
|---------------------------------------------|------------------------------------|-----------|--------|
| `ErrorNumber<runtimeexception.errornumber>` | `Integer</api/data_types/integer>` |           |        |
| `Message<runtimeexception.message>`         | `String</api/data_types/string>`   |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                         | Parameters                                                                                              | Returns                                    | Shared |
|----------------------------------------------|---------------------------------------------------------------------------------------------------------|--------------------------------------------|--------|
| `Constructor<runtimeexception.constructor0>` | message As `String</api/data_types/string>` = "", errorNumber As `Integer</api/data_types/integer>` = 0 |                                            |        |
| `Stack<runtimeexception.stack>`              |                                                                                                         | `String()</api/data_types/string>`         |        |
| `StackFrames<runtimeexception.stackframes>`  |                                                                                                         | `StackFrame()</api/exceptions/stackframe>` |        |

## Property descriptions

<div id="runtimeexception.errornumber">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

RuntimeException.ErrorNumber

**ErrorNumber** As `Integer</api/data_types/integer>`

> Used to contain an error number that describes the runtime error.

<div id="runtimeexception.message">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

RuntimeException.Message

**Message** As `String</api/data_types/string>`

> Used to contain descriptive text to display when the runtime exception is encountered.

## Method descriptions

<div id="runtimeexception.constructor0">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

RuntimeException.Constructor

**Constructor**(message As `String</api/data_types/string>` = "", errorNumber As `Integer</api/data_types/integer>` = 0)

> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> `Constructors</api/language/constructor>` are special methods called when you create an object with the `New</api/language/new>` keyword and pass in the parameters above.
>
> </div>
>
> Used to raise your own <span class="title-ref">RuntimeException</span> with a *message* and optional error number.

<div id="runtimeexception.stack">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

RuntimeException.Stack

**Stack** As `String()</api/data_types/string>`

> Returns a `String</api/data_types/string>` array that contains a list of all of the methods in the stack from the main entrypoint to the point at which the exception was invoked.
>
> The stack contains all the method names up and including the current method name.
>
> This feature only works if the **IncludeFunctionNames** property on the App object is selected in the Shared Build Settings.
>
> In addition to your own method calls, you will also see framework method calls, but these may not always be completely accurate due to insufficient symbols for the OS to resolve.

<div id="runtimeexception.stackframes">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

RuntimeException.StackFrames

**StackFrames** As `StackFrame()</api/exceptions/stackframe>`

> Returns an array containing the stack when the exception was first raised.

## Notes

Use runtime exceptions to trap errors so they can be handled. For example, reading from or writing to an array element that does not exist will generate an `OutOfBoundsException</api/exceptions/outofboundsexception>`.

| Name                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `AndroidException</api/exceptions/androidexception>`                                   | An error occurred in an Android app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `COMException</api/exceptions/comexception>`                                           | Raised anytime an exception occurs within any ActiveX/COM component that has been added to your project.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `CryptoException</api/exceptions/cryptoexception>`                                     | There was a problem using a Crypto function.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `DatabaseException</api/exceptions/databaseexception>`                                 | A `Database</api/databases/database>` error occurred.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `EndException</api/exceptions/endexception>`                                           | `Quit</api/language/quit>` was called causing the application to quit gracefully. See `EndException</api/exceptions/endexception>` for very important information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `FunctionNotFoundException</api/exceptions/functionnotfoundexception>`                 | A function declared using the `Declare</api/language/declare>` statement's "Soft" keyword could not be loaded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `HTMLViewerException</api/exceptions/htmlviewerexception>`                             | There was an error parsing the HTML using `HTMLViewer</api/deprecated/htmlviewer>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `IllegalCastException</api/exceptions/illegalcastexception>`                           | You cast an object to a different class and sent it a message its real class can't accept.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `IllegalLockingException</api/exceptions/illegallockingexception>`                     | Mutex Enter and Leave calls are in the wrong order. You cannot leave before you enter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `InvalidArgumentException</api/exceptions/invalidargumentexception>`                   | Raised when an invalid argument is passed to a function.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `InvalidParentException</api/exceptions/invalidparentexception>`                       | You tried to get the parent of a control using the Parent property of the `Control</api/deprecated/control>` class, but its parent is in a different window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `IOException</api/exceptions/ioexception>`                                             | An error occurred while creating or opening a file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `IteratorException</api/exceptions/iteratorexception>`                                 | Raised when an error or a change occurs in the data being iterated over.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `JSONException</api/exceptions/jsonexception>`                                         | A method of the `JSONItem</api/text/json/jsonitem>` class failed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `KeychainException</api/exceptions/keychainexception>`                                 | A method of the `Keychain</api/macos/keychain>` or `KeychainItem</api/macos/keychainitem>` classes failed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `KeyNotFoundException</api/exceptions/keynotfoundexception>`                           | An attempt was made to access a `Dictionary</api/language/dictionary>` item with a key that the dictionary does not contain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `MenuHasParentException</api/exceptions/menuhasparentexception>`                       | A `MenuItem</api/deprecated/menuitem>` has been used several times. Currently only applies to Cocoa applications.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `NamespaceException</api/exceptions/namespaceexception>`                               | Raised in a web application when a control is created with the WebSDK but is missing its JavaScript namespace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `NetworkException</api/exceptions/networkexception>`                                   | A network exception occurred with `URLConnection</api/networking/urlconnection>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `NilObjectException</api/exceptions/nilobjectexception>`                               | An attempt was made to access an object that does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `NotificationException</api/exceptions/notificationexception>`                         | A notification could not be sent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `ObjCException</api/exceptions/objcexception>`                                         | An Objective-C exception around a `Declare</api/language/declare>` statement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `OLEException</api/exceptions/oleexception>`                                           | An OLE-related runtime exception occurred. Handle errors in Office Automation code via the `OLEException</api/exceptions/oleexception>` class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `OutOfBoundsException</api/exceptions/outofboundsexception>`                           | An attempt was made to read from or write to a value, character, or element outside the bounds of the object or data type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `OutOfMemoryException</api/exceptions/outofmemoryexception>`                           | Raised in certain cases when an operation cannot be completed due to insufficient memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `PlatformNotSupportedException</api/exceptions/platformnotsupportedexception>`         | Raised when a feature is not supported on a specific platform.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `RegExException</api/exceptions/regexexception>`                                       | The `RegEx</api/text/regular_expressions/regex>` engine issued a runtime exception. Currently this means that you used an invalid search pattern in a Regular Expression. In the future, other types of regular expression exceptions may be added.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `RegExSearchPatternException</api/exceptions/regexsearchpatternexception>`             | You used an invalid regular expression search pattern.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `RegistryAccessErrorException</api/exceptions/registryaccesserrorexception>`           | You tried to use the `RegistryItem</api/windows/registryitem>` class without proper access privileges or tried to use it under any macOS or Linux. It is a Windows-only feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ServiceNotAvailableException</api/exceptions/servicenotavailableexception>`           | Occurs if a requested service is not available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `SessionNotAvailableException</api/exceptions/sessionnotavailableexception>`           | Raised if no session is available to attach to a control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `ShellNotAvailableException</api/exceptions/shellnotavailableexception>`               | You tried to access a Shell that is not available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ShellNotRunningException</api/exceptions/shellnotrunningexception>`                   | You tried to access an asynchronous or interactive shell session, but the shell was not running.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `SpotlightException</api/exceptions/spotlightexception>`                               | An error related to a `SpotlightQuery</api/macos/spotlightquery>` was encountered, such as an invalid query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `StackOverflowException</api/exceptions/stackoverflowexception>`                       | When one routine (method/event handler/menu handler) calls another, memory is used to keep track of the place in each routine where it was called along with the values of its local variables. The purpose of this is to return (when the routine being called finishes) to the previous routine with all local variables as they were before. The memory set aside for tracking this is called the Stack (because you are "stacking" one routine on top of another). If your application runs out of stack space, a `StackOverflowException</api/exceptions/stackoverflowexception>` will occur. You should be able to test your application thoroughly enough to prevent this error from occurring. |
| `ThreadAccessingUIException</api/exceptions/threadaccessinguiexception>`               | You tried to access the user interface from code that is running in a `Thread</api/language/threading/thread>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ThreadAlreadyRunningException</api/exceptions/threadalreadyrunningexception>`         | You tried to change the stack size of a `Thread</api/language/threading/thread>` while it was running.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ThreadEndException</api/exceptions/threadendexception>`                               | A `Thread</api/language/threading/thread>` is quitting. See `ThreadEndException</api/exceptions/threadendexception>` for very important information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `TypeMismatchException</api/exceptions/typemismatchexception>`                         | You tried to assign to an object the wrong data type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `UnsupportedFormatException</api/exceptions/unsupportedformatexception>`               | You used a string expression that does not evaluate to a number or tried to open or save an unsupported picture format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `UnsupportedOperationException</api/exceptions/unsupportedoperationexception>`         | You tried to perform an operation which is not supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `XAMLException</api/exceptions/xamlexception>`                                         | An error occurring in a `DesktopXAMLContainer</api/user_interface/desktop/desktopxamlcontainer>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `XMLDOMException</api/exceptions/xmldomexception>`                                     | This exception may occur during the creation of a DOM document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `XMLException</api/exceptions/xmlexception>`                                           | There was an error in parsing XML.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `XMLReaderException</api/exceptions/xmlreaderexception>`                               | There was an error in parsing XML using `XMLReader</api/text/xml/xmlreader>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `XojoScriptAlreadyRunningException</api/exceptions/xojoscriptalreadyrunningexception>` | The user tried to modify an `XojoScript</api/language/xojo_script/xojoscript>` that is already executing or tried to modify the context of the script while it is running.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `XojoScriptException</api/exceptions/xojoscriptexception>`                             | An invalid `MemoryBlock</api/language/memoryblock>` was passed to the `Compile<xojoscript.compile>` method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

If you fail to trap a runtime error in an exception block, it will trigger the UnhandledException event of the `DesktopApplication</api/user_interface/desktop/desktopapplication>` class. You can then handle all runtime exceptions generically within that event handler.

When using the Office Automation plug-ins, you can include an exception block that references these classes. For example:

``` xojo
Exception err As OLEException
  MessageBox(err.message + " Error No.: " + err.ErrorNumber.ToString)
```

Third-party plug-ins may also incorporate their own types of runtime exceptions.

When you are testing your application in the IDE, execution will stop at the offending line and you will see an error message in your Code Editor. When the error occurs in a built application, the user will see a generic error message (as shown in the Notes section below) and quit - unless you include an exception handler.

Runtime Exceptions are used to catch errors in programming. Without an exception handler, the user will see a generic message box that a particular type of exception has occurred and the app will terminate itself. The text is usually "An exception of class \[ExceptionFromListAbove\] was not handled. The application must shut down." The app quits when the user clicks the OK.

Including exception handlers in your code allows you to display information that will help you determine the cause of the problem and prevents your application from quitting automatically.

Say, for example, you are getting an `OutOfBoundsException</api/exceptions/outofboundsexception>` when trying to access an element of an array. You could put in an exception handler to display the number of items in the array and the item number you were attempting to change along with any other useful information that would help you to track down the source of the bug. See the section on `OutOfBoundsException</api/exceptions/outofboundsexception>` for an example of this.

There is another example of exception handling in the section on `IllegalCastException</api/exceptions/illegalcastexception>`.

## Sample code

You can use several `Exception</api/exceptions/exception>` blocks, each of which handles a specific type of runtime exception. An exception not caught by one of the blocks will be raised up the calling chain.

``` xojo
Var f As FolderItem
Try
  f.Remove
Catch e As NilObjectException
  MessageBox("Nil Object")
Catch e As OutOfBoundsException
  MessageBox("Out of Bounds")
Catch e As TypeMismatchException
  MessageBox("Type Mismatch")
End Try
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

The following example checks for the type of exception and handles the exception if it is a `NilObjectException</api/exceptions/nilobjectexception>`. If the exception is not a `NilObjectException</api/exceptions/nilobjectexception>`, it lets execution continue through the calling chain by calling `Raise</api/language/raise>`

``` xojo
Var f As FolderItem
Try
  f.Remove
Catch e As NilObjectException
  MessageBox("Nil Object")
Catch e As RunTimeException
  Raise e
End Try
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

`Introspection</api/language/introspection/introspection>` provides a means of getting the exception type at runtime for logging or other purposes. You can add this functionality in a general way as follows.

First, define a module, named for example RuntimeExceptionExtension. To it, add the following function.

``` xojo
Function Type(Extends e As RuntimeException) As String
 Var t As Introspection.TypeInfo = Introspection.GetType(e)
 If t <> Nil Then
   Return t.FullName
 Else
   ' this should never happen...
    Return ""
 End If
End Function
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

This allows you to write code like the following:

``` xojo
Try
  ' your code here
Catch e As RuntimeException
  MessageBox("An exception of type " + e.Type + " was caught.")
End Try
```

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `Catch</api/language/catch>`, `Raise</api/language/raise>`, `Exception</api/exceptions/exception>`, `Try</api/language/try>` statements; `Nil</api/language/nil>` datatype.

</div>