Errors

The SDK reports a failure in one of two ways:

• A failed call. A call on the runtime or on a store fails at once: creating the runtime, calling a static helper, mounting a store, dispatching an action or subscribing, and on the web also reading state while no listener is subscribed. The call throws.
• Store state. The work behind an action fails later, for example a request that Folio rejects. dispatch has already returned; the failure appears in the state of the store.

Naming across platformsCopy Anchor Link

Every error type is generated from one definition, so the cases are the same on every platform. This page names cases as Kotlin does. The error types come in two shapes.

Tagged cases. InquiryError, SessionStartError, AuthError, VaultError, MrtdUiError, ImageProcessingError, InvalidCalendarValue, AttachmentReadError, LogError and the reasons OtpErrorReason, GovIdErrorReason, SelfieErrorReason and EmbedFailure:

In TypeScript each of these types also has a factory or constant per case in lowerCamelCase, such as InquiryError.recordMapping(message) and InquiryError.invalidEntry.

ImageProcessingError, InvalidCalendarValue and AttachmentReadError are exported in these shapes, but no call hands your app one of their values. A call that fails because of one of them throws a failed call error whose message is the text of the case.

ImageProcessingError carries its text in a single field value: .insufficientData(value:) in Swift, ImageProcessingError.InsufficientData(value) in Kotlin, and { type: 'INSUFFICIENT_DATA', value: '<text>' } in TypeScript, where value is the string itself, not an object.

Codes. CoreError is a plain enumeration: an enum with a UInt8 raw value in Swift (.invalidComponent), an enum class with a value in Kotlin (CoreError.INVALID_COMPONENT), and a string in TypeScript ('INVALID_COMPONENT', also CoreError.INVALID_COMPONENT).

In TypeScript, match a case by its type:

if (lifecycle.type === 'FAILED' && lifecycle.value.error.type === 'RECORD_MAPPING') {
    reportMapperFailure(lifecycle.value.error.value.message);
}

The inquiry UI needs no such check: it shows the notice in InquiryUiModel.failure, whose texts the SDK has already chosen. See Failure notice.

A failed callCopy Anchor Link

A call on a store fails because of a CoreError, FolioSdk.create because of a SessionStartError, an image helper because of an ImageProcessingError, a calendar value constructor because of an InvalidCalendarValue and getBytes() of an attachment because of an AttachmentReadError. In every case the call throws the platform's error type, whose message describes the failure; the SDK error itself is not handed to your app:

do {
    try store.dispatch(action: .close)
} catch let error as FolioSDKError {
    log(error.message)
} catch {
    log(String(describing: error))
}

On Android, rememberFolioSdk does not throw: it reports a failed create as FolioSdkStartup.Failed with the exception in error. See Runtime and stores.

On the web, message is the SDK's message for the failure, or the status name when the SDK recorded none. The SDK also prints every FolioSDKError it throws with console.error, prefixed [FolioSDK]; see Create the runtime.

A store keeps its state current by reading a subscription in the background. When that stream fails, the error is kept in streamError: a @Published Error? on iOS and a StateFlow<Throwable?> on Android. On the web the store keeps it and throws it from state.

Error codesCopy Anchor Link

The code of FolioSDKError on iOS and of FolioSDKException on Android, and status and lastError of FolioSDKError on the web, are codes of the bridge between your app and the SDK's native code. The numbers are the same on every platform:

In Swift, code is a FolioSDKErrorCode; compare its number, error.code.rawValue, a UInt32. In Kotlin, code is an Int and the constants are members of FolioSDKException. In TypeScript, FolioSDKErrorCode is exported from @folio/sdk, and statusName and lastErrorName hold the names from this table, or unnamed(<code>) for a number the table does not list.

BorrowConflict means that the call needed an SDK object in a way that conflicts with its current use: exclusive access to an object that is in use elsewhere, or any access to an object that another call holds exclusively. Its message is handle has conflicting shared or exclusive access.

A call that fails because of an SDK error, such as a CoreError, a SessionStartError, an ImageProcessingError, an InvalidCalendarValue or an AttachmentReadError, throws with code InternalError (8); the SDK error shows only in message, as its text. The numeric codes of CoreError are not bridge codes.

Bridge failuresCopy Anchor Link

Some interfaces of the SDK are implemented by your app, such as the IdentityRecordMapper you pass to FolioSdk.create. The SDK reports a failure of such an implementation to a bridge error handler when a method that cannot return an error throws, or when the arguments or the return value of a method cannot be converted. It reports the failure of a store's stream to the same handler. The handler receives the site, <Interface>.<method> or <Store>.stream, and the error.

Set the handler to send these failures to your own logging, for example to the SDK logger. An error that a method can return, such as an IdentityMappingError from map, reaches the SDK as that error and is not reported, and neither is cancellation. A store stream failure also stays visible in the store's streamError, as described in A failed call.

CoreErrorCopy Anchor Link

The error of the store runtime. Each case has a fixed numeric code: the raw value in Swift and value in Kotlin.

The actions of the session, authentication, vault, Folio document and logs stores wait in one queue of at most 256 actions, shared by all the stores mounted on the runtime. When the queue is full, dispatch throws StoreOverflow. Every action of the inquiry store except the PreviewFrame intent, and every action of the NFC store, skips this queue, so it goes through even when the queue is full. A PreviewFrame that arrives while the queue is full is dropped, and its dispatch does not throw.

SessionStartErrorCopy Anchor Link

FolioSdk.create fails with it, and SessionUiModel.error carries it when the last sign-out failed. See Session.

status is UInt16 in Swift, Int in Kotlin and number in TypeScript.

ImageProcessingErrorCopy Anchor Link

The error of the image helpers FolioSdk.barcodeImage, FolioSdk.computeMetrics and FolioSdk.rotateImage. The helper throws a failed call error with code InternalError (8) whose message is the text of the case. Every case except EmptyImageData carries a text that describes the failure.

The message is the text of the case alone; no case name or prefix precedes it. For example, barcodeImage with an empty value throws empty barcode value, barcodeImage of an Ean13 barcode with the value abc throws barcode encode failed: IllegalArgumentException - Requested contents should be 12 or 13 digits long, but got 3, and computeMetrics of a 10 × 10 RGBA image with no data throws data length (0) < expected (400) for 10x10 Rgba.

InvalidCalendarValueCopy Anchor Link

The failures of the calendar values. When a part is out of range or the text is not in the accepted format, new and parse throw a failed call error with code InternalError (8) whose message is the text of the case, such as "2026-02-29" is not a calendar date for Date. No call returns the case as a value.

text is the value that was rejected. For new it is the parts written as ISO 8601 text, such as 2026-02-29. millis is Int64 in Swift, Long in Kotlin and bigint in TypeScript.

AttachmentReadErrorCopy Anchor Link

The failures of getBytes() on an AttachmentRef, such as a photo of a Folio document. The call throws a failed call error with code InternalError (8) whose message is the text of the case, such as attachment access has expired for Expired. No call returns the case as a value.

expected and actual are sizes in bytes: UInt64 in Swift, Long in Kotlin and bigint in TypeScript.

AuthErrorCopy Anchor Link

The error of a sign-in. It reaches you in AuthUiModel.flow:

• A retryable error, while a step waits for input, comes as AwaitingInput with an error. The person can try again on the same step.
• A terminal error, or a retryable one while no step waits, comes as Failed with an error. The sign-in ended; start it again.

See Authentication.

until of Locked is a Unix time in seconds: Int64? in Swift, Long? in Kotlin and bigint | undefined in TypeScript. retryAfter of RateLimited is a wait in seconds: UInt64? in Swift, Long? in Kotlin and bigint | undefined in TypeScript.

VaultErrorViewCopy Anchor Link

VaultUiModel.error wraps the vault's error with its code:

VaultErrorCopy Anchor Link

The error of the vault. It reaches you in details of VaultUiModel.error. See Vault and Sharing.

format of EncoderUnavailable is an ImageFormat. version of UnsupportedBodyVersion and limitBytes of FileTooLarge are UInt32 in Swift, Long in Kotlin and number in TypeScript.

InquiryErrorViewCopy Anchor Link

InquiryUiModel.error is not the raw error but its projection for the screen:

See Errors in the model for the placement rules.

InquiryErrorCopy Anchor Link

The error of an inquiry. It reaches you as the raw value in InquiryLifecycle.Failed, and it is the source of InquiryUiModel.error. The placement and retryable columns describe that projection, an InquiryErrorView: where the error is shown, with which text, and whether it offers a retry. A failure of a Resume entry before its first step never offers one. The field of an Otp error is value, the contactField or codeField of the step. A case that says the update is not applied leaves the previous step on screen.

length of InvalidCodeLength and day of InvalidWeekday are Int64 in Swift, Long in Kotlin and bigint in TypeScript. limitBytes of FileTooLarge is UInt32 in Swift, Long in Kotlin and number in TypeScript. code of GovId is optional: String? in Swift and Kotlin, string | undefined in TypeScript. In Swift the case is .govId(reason:code:message:).

The code names the error in the SDK's debug log: a failed inquiry request is logged as the warning inquiry effect failed with the code in error_code, for example inquiry.tokenExpired. See Logging.

OTP reasonsCopy Anchor Link

OtpErrorReason, the reason of an Otp error. The reasons marked "at the field" are shown at the step's value field with the message from Folio: the contact field (contactField) while the email address or phone number is entered, and the code field (codeField) while the code is entered. InvalidTarget, MissingTarget and DeliveryFailed concern the contact. The others are banners without text.

When RecoveryRequired comes back while the SDK runs a verification command of the step, the SDK reports the command to Folio as rejected instead of showing the error, and Folio decides how the step goes on. The same holds for the selfie reason RecoveryRequired.

GovId reasonsCopy Anchor Link

GovIdErrorReason, the reason of a GovId error. It covers the document photo check, the NFC chip check and the face match. A Cached reason concerns a verification result saved earlier that the inquiry presented again instead of a new capture.

Selfie reasonsCopy Anchor Link

SelfieErrorReason, the reason of a Selfie error.

Embed errorsCopy Anchor Link

The embed loader reports its own failures through onLifecycle as a FAILED lifecycle whose error is an InquiryError. See Inquiry embed.

EmbedFailure, the reason of Embed, has the cases InvalidOptions, ReadyTimeout, OriginRejected and VersionMismatch. In TypeScript the fields sit under value, for example lifecycle.value.error.value.reason.type.

MrtdUiErrorCopy Anchor Link

The error of an NFC chip read, in MrtdUiModel.error. Every case has a message, the text to show in the runtime's current locale, which the SDK chooses for the cause. See NFC chip reading for the text of each cause.

IdentityMappingErrorCopy Anchor Link

The failure of your IdentityRecordMapper. IdentityMappingError is a value with one field, message: a struct in Swift, a data class in Kotlin and an interface in TypeScript.

To report a failure, throw from map: any Error on iOS and the web, any exception on Android. The SDK turns what you throw into an IdentityMappingError with its message. On the web the message is the error's message. On iOS it is message of a thrown FolioSDKError; otherwise it is errorDescription of a LocalizedError when that is set, and String(describing:) of the error otherwise. The mapper runs before any write, so the SDK then saves nothing, and the inquiry ends with InquiryLifecycle.Failed and the InquiryError RecordMapping with that message. See Identity records.