Handle Errors - Kotlin SDK
On this page
The Kotlin SDK uses a hierarchy of exceptions to help developers manage API call failures. There are two major categories of exceptions that your application should handle when using the Kotlin SDK:
- realm errors occur when a read or write to realm database fails. These errors generate a RealmException.
- app errors occur when network communication with App Services fails. These errors generate an AppException.
Some errors are ephemeral: they happen because of failures outside of the client or SDK's control. A failed login attempt due to a network error is an example of an ephemeral error.
Other errors require logic fixes. Examples include:
- writing to a realm outside of a write transaction
- a failed login attempt due to incorrect credentials
- deleting an object that does not exist
When an ephemeral error occurs, you should retry the operation that caused the error. If the operation still fails when you retry it, investigate logic fixes.
Example
You can handle errors in the SDK with Kotlin's built-in
runCatching
API. Use the onSuccess
and onFailure
callbacks of the returned
Result
to handle successful SDK API calls and error cases. The following example
logs an anonymous user into an App. If the login attempt succeeds, we
log the successful authentication attempt and transition the
user to another screen. If the login attempt fails, we handle each
potential error case individually:
- If the user supplied invalid credentials, we log the attempt and display a popup toast encouraging the user to check their credentials.
- If there was a problem with the network connection, we log the problem to the error log and display a popup toast encouraging the user to check their network connection and try again.
- For all other errors, we log the problem to the error log and display a popup toast informing the user that the login attempt failed.
val app = App.create(YOUR_APP_ID) runCatching { app.login(Credentials.emailPassword(email, password)) }.onSuccess { Log.v("Successfully logged in") // transition to another activity, load a fragment, to display logged-in user information here }.onFailure { ex: Throwable -> when (ex) { is InvalidCredentialsException -> { Log.v("Failed to login due to invalid credentials: ${ex.message}") Toast.makeText(baseContext, "Invalid username or password. Please try again.", Toast.LENGTH_LONG).show() } is ConnectionException -> { Log.e("Failed to login due to a connection error: ${ex.message}") Toast.makeText(baseContext, "Login failed due to a connection error. Check your network connection and try again.", Toast.LENGTH_LONG).show() } else -> { Log.e("Failed to login: ${ex.message}") // generic error message for niche and unknown fail cases Toast.makeText(baseContext, "Login failed. Please try again.", Toast.LENGTH_LONG).show() } } }