Class

# KeychainException

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

## Description

A method of the `Keychain</api/macos/keychain>` or `KeychainItem</api/macos/keychainitem>` classes failed. See the error code returned by <span class="title-ref">KeychainException</span> to diagnose the problem.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

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

## Methods

<div class="rst-class">

table-centered_column_4

</div>

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

## Property descriptions

<div id="keychainexception.errornumber">

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

</div>

<div class="rst-class">

forsearch

</div>

KeychainException.ErrorNumber

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

> Used to contain an error number that describes the runtime error.
>
> The following example displays a message box if, for example, you try to create more than one `KeychainItem</api/macos/keychainitem>` for the same application.
>
> ``` xojo
> Var newItem As KeychainItem
> If System.KeychainCount > 0 Then
>   newItem = New KeychainItem
>   ' Indicate the name of the application
>   newItem.ServiceName = "MyApplication"
>
>   ' Create a new keychain item for the application and assign the password
>   System.Keychain.AddPassword(newItem, "SecretPassword")
> Else
>   System.Beep
>   MessageBox("You don't have a key chain.")
> End If
> Exception err As KeychainException
>   MessageBox(err.Message + ". Error Code: " + err.ErrorNumber.ToString)
> ```

<div id="keychainexception.message">

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

</div>

<div class="rst-class">

forsearch

</div>

KeychainException.Message

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

> Used to contain descriptive text to display when the runtime exception is encountered.
>
> The following example displays a message box if, for example, you try to create more than one `KeychainItem</api/macos/keychainitem>` for the same application.
>
> ``` xojo
> Var newItem As KeyChainItem
> If System.KeyChainCount > 0 Then
>   newItem = New KeyChainItem
>   ' Indicate the name of the application
>   newItem.ServiceName = "MyApplication"
>
>   ' Create a new keychain item for the application and assign the password
>   System.KeyChain.AddPassword(newItem, "SecretPassword")
> Else
>   System.Beep
>   MessageBox("You don't have a key chain.")
> End If
> Exception err As KeyChainException
>   MessageBox(err.Message + ". Error Code: " + err.ErrorNumber.ToString)
> ```

## Method descriptions

<div id="keychainexception.constructor0">

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

</div>

<div class="rst-class">

forsearch

</div>

KeychainException.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="keychainexception.stack">

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

</div>

<div class="rst-class">

forsearch

</div>

KeychainException.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="keychainexception.stackframes">

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

</div>

<div class="rst-class">

forsearch

</div>

KeychainException.StackFrames

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

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

## Notes

The following tables shows the values of ErrorNumber and the associated text returned in the Message property.

| Error Number | Message                            |
|--------------|------------------------------------|
| -128         | User Cancelled.                    |
| -25291       | Keychain not available.            |
| -25292       | Keychain read only.                |
| -25293       | Keychain Authorization failed.     |
| -25294       | No such Keychain.                  |
| -25295       | Invalid Keychain.                  |
| -25296       | Duplicate Keychain.                |
| -25797       | Keychain Duplicate Callback.       |
| -25298       | Keychain Invalid Callback.         |
| -25299       | Keychain Duplicate Item.           |
| -25300       | Keychain Item Not Found.           |
| -25301       | Keychain Buffer Too Small.         |
| -25302       | Keychain Data Too Large.           |
| -25303       | Keychain No Such Attribute.        |
| -25304       | Keychain Invalid Item Reference.   |
| -25305       | Keychain Invalid Search Reference. |
| -25306       | Keychain No Such Class.            |
| -25307       | No Default Keychain.               |
| -25308       | Keychain Interaction Not Allowed.  |
| -25309       | Keychain Read Only Attribute.      |
| -25310       | Wrong Keychain Version.            |
| -25311       | Keychain Key Size Not Allowed.     |
| -25312       | Keychain No Storage Module.        |
| -25313       | Keychain No Certificate Module.    |
| -25314       | Keychain No Policy Module.         |
| -25315       | Keychain Interaction Required.     |
| -25316       | Keychain Data Not Available.       |
| -25317       | Keychain Data Not Modifiable.      |
| -25318       | Keychain Create Chain Failed.      |

## Sample code

The following example displays a message box if, for example, you try to create more than one `KeychainItem</api/macos/keychainitem>` for the same application.

``` xojo
Var NewItem As KeychainItem
If System.KeychainCount > 0 Then
  newItem = New KeychainItem
  ' Indicate the name of the application
  newItem.ServiceName = "MyApplication"

  Try
    ' Create a new keychain item for the application and assign the password
    System.Keychain.AddPassword(newItem, "SecretPassword")
  Catch error As KeychainException
    MessageBox(error.Message + ". Error Code: " + error.errorNumber.ToString)
  End Try
Else
  System.Beep
  MessageBox("You don't have a key chain.")
End If
```

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

The following example uses an `Exception</api/exceptions/exception>` block to display a message box if the application specified by ServiceName does not have a `KeychainItem</api/macos/keychainitem>`.

``` xojo
Var itemToFind As KeychainItem
Var password As String

itemToFind = New KeychainItem

' Indicate the name of the application whose keychain item you wish to find
itemToFind.ServiceName = "MyApplication"

Try
  ' get application's password from the system keychain
  password = System.Keychain.FindPassword(itemToFind)
  MessageBox("The password for this item is: " + password)
Catch error As KeychainException
  MessageBox("Can't find item: " + error.Message)
End Try
```

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | All                   |

<div class="seealso">

`RuntimeException</api/exceptions/runtimeexception>` parent class; `Keychain</api/macos/keychain>`, `KeychainItem</api/macos/keychainitem>` classes; `System</api/os/system>` module.

</div>