> ## Documentation Index
> Fetch the complete documentation index at: https://filekit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Dialog error handling

> Handle FileKit dialog results, cancellation, and operational failures

FileKit keeps successful results, user cancellation, operational failures, and programmer errors separate. New Compose integrations should use launcher overloads with an explicit `onError` callback.

## Callback contract

| Outcome                                                               | `onResult`                            | `onError`                                           | Propagates             |
| --------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------- | ---------------------- |
| A value-returning picker, directory picker, saver, or camera succeeds | Called once with the value            | Not called                                          | No                     |
| The user dismisses a value-returning dialog                           | Called once with `null`               | Not called                                          | No                     |
| Android camera permission is denied                                   | Called once with `null`               | Not called                                          | No                     |
| A valid FileKit operation cannot start or complete                    | Not called                            | Called once with a `FileKitDialogException` subtype | No                     |
| The launcher coroutine is cancelled                                   | Not called                            | Not called                                          | Cancellation           |
| The invocation is invalid or an unexpected defect occurs              | Not called                            | Not called                                          | The original exception |
| Your `onResult` or `onError` callback throws                          | No compensating callback is delivered | No compensating callback is delivered               | The callback exception |

`FileKitPickerException` is the picker-specific subtype of `FileKitDialogException`. FileKit does not convert invalid arguments, unsupported argument combinations, or unexpected defects into operational failures.

## State-tracking picker modes

`SingleWithState` and `MultipleWithState` report progress and their represented terminal outcome through `onResult`:

* `Started` and `Progress` are non-terminal values.
* Exactly one of `Completed`, `Cancelled`, or `Failed` is the represented terminal value.
* `FileKitPickerState.Failed` remains data delivered to `onResult`; it is not duplicated through `onError`.
* A picker failure thrown outside the state stream is delivered to `onError`.
* Coroutine cancellation stops delivery and produces no later terminal callback.

## Sharing

Sharing has no success callback. A successful share launch, including user dismissal after the system share UI appears, remains callback-less. A FileKit-owned operational failure is delivered to `onError`; coroutine cancellation, invalid invocation, unexpected defects, and callback exceptions propagate.

## Compatibility overloads

Launcher overloads without `onError` remain available for source and binary compatibility. They preserve their historical callback shape and ignore normalized operational failures without logging. They do not swallow coroutine cancellation, invalid invocation, unexpected defects, or exceptions thrown by your callbacks.