Class

# NilObjectException

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

## Description

Occurs when code tries to access an object that doesn't exist.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

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

## Methods

<div class="rst-class">

table-centered_column_4

</div>

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

## Property descriptions

<div id="nilobjectexception.errornumber">

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

</div>

<div class="rst-class">

forsearch

</div>

NilObjectException.ErrorNumber

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

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

<div id="nilobjectexception.message">

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

</div>

<div class="rst-class">

forsearch

</div>

NilObjectException.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="nilobjectexception.constructor0">

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

</div>

<div class="rst-class">

forsearch

</div>

NilObjectException.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 `RuntimeException</api/exceptions/runtimeexception>` with a *message* and optional error number.

<div id="nilobjectexception.stack">

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

</div>

<div class="rst-class">

forsearch

</div>

NilObjectException.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="nilobjectexception.stackframes">

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

</div>

<div class="rst-class">

forsearch

</div>

NilObjectException.StackFrames

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

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

## Notes

A <span class="title-ref">NilObjectException</span> occurs when you use a property or variable to access an object that doesn't exist. For example, when the `FolderItem.Constructor</api/files/folderitem>` method is passed an invalid pathname, it returns `Nil</api/language/nil>`. Certain functions that are designed to return `FolderItems</api/files/folderitem>` on one platform may return `Nil</api/language/nil>` when run on other platforms. If your code attempts to access or write to a property of a `Nil</api/language/nil>` `FolderItem</api/files/folderitem>`, a <span class="title-ref">NilObjectException</span> will occur.

A function also returns `Nil</api/language/nil>` if there isn't enough memory to load the object. For example, if you tried to load a large picture into memory but your application didn't have enough RAM left to load the picture, the function used to load the picture would return `Nil</api/language/nil>`.

Immediately after calling a function that returns an object (like `FolderItem.Constructor</api/files/folderitem>`, for example) you should check the object to see if it is `Nil</api/language/nil>` or add an `Exception</api/exceptions/exception>` or `Try</api/language/try>` block to the end of the method that handles NilObjectExceptions. Any function's result that is not a data type is an object and should be checked.

## Sample code

This example tries to open a jpeg file using the `FolderItem's Constructor method</api/files/folderitem>` and display it in an `DesktopImageViewer</api/user_interface/desktop/desktopimageviewer>`. If the pathname passed to the `FolderItem</api/files/folderitem>` is invalid, it returns `Nil</api/language/nil>`. The <span class="title-ref">NilObjectException</span> is handled in the `Exception</api/exceptions/exception>` block which is after the last "regular" line of the method.

If the pathname is valid, but the item does not exist, the `FolderItem's Constructor</api/files/folderitem>` returns a valid `FolderItem</api/files/folderitem>` whose NativePath property is equal to the pathname. You should check the Exists property of the `FolderItem</api/files/folderitem>` to determine whether the file exists before trying to do something with the `FolderItem</api/files/folderitem>`.

This code, in other words, checks for two different problems — invalid pathname and valid path to a nonexistent file.

``` xojo
Var file As FolderItem
Try
  file = New FolderItem("/Users/fred/Documents/Fluffy.jpeg", FolderItem.PathModes.Native)
  If Not file.Exists Then
    System.Beep
    MessageBox("The file " + file.NativePath + "doesn't exist!")
  Else ' document exists
    ImageViewer1.Image = Picture.Open(file)
  End If
Catch e As NilObjectException
  MessageBox("Invalid pathname!")
End Try
```

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

The following example creates a new, empty picture. If there isn't enough memory to create the picture, `Nil</api/language/nil>` will be returned by the `Picture</api/graphics/picture>` constructor. The example code checks for this and informs the user:

``` xojo
Var p As New Picture(10000, 10000)
If p = Nil Then
  System.Beep
  MessageBox("There isn't enough memory available to create the picture.")
Else
  ' do something with the picture here
End If
```

## Compatibility

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

<div class="seealso">

`RuntimeException</api/exceptions/runtimeexception>` parent class; `Function</api/language/function>`, `Catch</api/language/catch>`, `Raise</api/language/raise>` statements; `Nil</api/language/nil>` datatype; `Exception</api/exceptions/exception>`, `Try</api/language/try>` statements; `Exception Handling</getting_started/debugging/exception_handling>` topic

</div>