Docs Menu

Docs HomeRealm

Handle App Errors - Kotlin SDK

On this page

  • Service Errors
  • Connection Errors
  • Bad Request Errors
  • Auth Errors
  • User Already Confirmed Errors
  • User Not Found Errors
  • User Already Exists Errors
  • Invalid Credentials Errors
  • Sync Errors
  • Unrecoverable Sync Errors
  • Wrong Sync Type Errors
  • Bad Flexible Sync Query Errors

App errors fall into two major categories: ServiceException and SyncException.

Service errors occur when an Atlas App Services request fails at the HTTP level, i.e. the HTTP request returned, but the HTTP Status code was not 200 (OK).


See also:

Connection errors happen when HTTP communication fails between the SDK and the App Services backend, ie. the HTTP request isn't able to receive a status code.

Because these errors stem from network layers outside of the SDK's control, you should consider these errors ephemeral. Retry the operation, then investigate the error if the retry fails. If the operation fails because the client device is offline, you can ask the app user to retry the operation when they reconnect to the internet.


Bad request errors come from malformed App Services requests.

When you get a bad request error:

  • Check the inputs for the operation.

  • Check your App logs for more information about what went wrong.


Auth errors happen when a user account action, such as login, logout, or registration, fails. Usually, you'll get a more specific subtype that helps you identify a solution.


See also:

User already confirmed errors occur when you attempt to confirm a user who you have already confirmed.

When you get a user already confirmed error, it's best to not disrupt the application flow. Since the user is confirmed, you can safely proceed to log in. There is no need to retry confirmation.

User not found errors occur when the App Services backend cannot find a user with the supplied username. This is commonly caused by typos in email/password usernames.

When you experience this error, prompt the user to re-enter their username and try again.

User already exists errors occur when a client attempts to register a user with a username that is already in use in that App.

When you experience this error, prompt users to:

  • use a different username

  • login with their existing username if they already have an account

Invalid credential errors occur when a JWT, email/password, or API Key user login fails due to invalid credentials. Other authentication providers throw an Auth Error instead.

Sync errors occur when Device Sync fails.


See also:

Unrecoverable sync errors happen when Device Sync fails catastrophically. This usually means a bug in the client or connected App.

When an unrecoverable sync error occurs, you should surface the problem to the end user. Let them know that Device Sync won't work until the problem is solved. It's best to send yourself an alert so you can check the backend App logs and fix the problem as soon as possible.

Wrong sync type errors happen when the client and App use different sync protocols. The SDK supports two kinds of sync: flexible sync and partition based. sync. When a client connects to an App using a sync type that does not match the App's sync type, a wrong sync type error occurs.

To recover from a wrong sync type error, update the client to use a sync type that matches the backend. This will most likely require the user to update to a new version of your app containing the fix.

Bad flexible sync query errors happen when you try to subscribe to a flexible sync query that is not supported by the App backend. This can happen when you:

  • query a field not specified as a queryable field in your flexible sync configuration

  • create a flexible sync query using operators unsupported by flexible sync

To recover from a bad flexible sync query error, update your client to use a sync query compatible with your App configuration. This will most likely require the user to update to a new version of your app containing the fix.

←  Handle Realm Errors - Kotlin SDKMigrate from the Java SDK to the Kotlin SDK →
Share Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.