Results and errors

How FileKit dialogs report results, cancellation, and failures in Compose and the suspend API

Every FileKit dialog separates three outcomes: a value, a user cancellation (null), and an operational failure (a FileKitDialogException). Invalid arguments and unexpected defects are never converted into failures: they propagate as the original exception.

​

Compose launchers

Use the launcher overloads that take onError. The trailing lambda is onResult:

val launcher = rememberFilePickerLauncher(
    onError = { failure -> showError(failure.message) },
) { file ->
    // file is null when the user cancelled
}

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

rememberFilePickerLauncher passes a FileKitPickerException (the picker subtype of FileKitDialogException) to onError. The directory picker, file saver, camera, and share launchers pass a FileKitDialogException.

If a dialog never appears on iOS, check where the launcher is remembered: see Compose launchers.

​

Suspend API

The FileKit.open… functions return null when the user cancels and throw on operational failures:

Function	On cancel	Throws
openFilePicker (Single, Multiple)	null	FileKitPickerException
openDirectoryPicker, openFileSaver, openCameraPicker	null	FileKitDialogException
shareFile	Returns normally	FileKitDialogException

val file = try {
    FileKit.openFilePicker()
} catch (e: FileKitPickerException) {
    showError(e.message)
    null
}

Coroutine cancellation and invalid arguments (for example maxItems outside 1..50) propagate as usual. Catch FileKitDialogException to handle every dialog failure in one place.

​

State-tracking picker modes

FileKitMode.SingleWithState and MultipleWithState deliver progress and their terminal outcome as FileKitPickerState values, through onResult in Compose or the returned Flow in the suspend API:

• Started and Progress are non-terminal values.
• Exactly one of Completed, Cancelled, or Failed is the terminal value.
• FileKitPickerState.Failed is data: it is not duplicated through onError.
• A picker failure thrown outside the state stream reaches onError (or is thrown while collecting the flow).
• Coroutine cancellation stops delivery and produces no later terminal value.

​

Sharing

Sharing has no success callback. A successful share launch, including user dismissal after the system share sheet appears, stays callback-less. A FileKit-owned operational failure reaches onError. Coroutine cancellation, invalid invocations, unexpected defects, and callback exceptions propagate.

​

Compatibility overloads

Launcher overloads without onError remain available for source and binary compatibility. They keep their historical callback shape and ignore operational failures without logging. They still propagate coroutine cancellation, invalid invocations, unexpected defects, and exceptions thrown by your callbacks.

Prefer the onError overloads in new code so failures are visible.

​

Related

• File picker for picking modes, including state tracking.
• Dialogs setup for where to remember launchers.