Realm Weekly Bytes #3: Lets Talk Bad Changeset Error

We spoke about error handling last week, so will continue on the same trend this week as the “Bad Changeset” error has been frequently asked by a lot of you and it sometimes gets tricky to troubleshoot why this is happening or how this can be fixed.

This week, let’s learn some tips and tricks around the error, and some proactive steps you can take to prevent this error from happening.

*Depending on the use-case and implementation of code in your application, sometimes the error can still happen, but hopefully with the information below you will have more understanding of the Sync process.

What is a changeset?

A changeset is a set of instructions that specify a change(s) to a Realm object(s) after a write operation. This along with some metadata is exchanged between a client(mobile) and the Sync Server to keep your data in Sync. Check Realm Sync Protocol section to learn more.

What is a Bad Changeset?

A changeset is termed as Bad when instructions from the client do not match the server (UPLOAD) that leads to Server-side error or when the instructions from the Server do not match the client (DOWNLOAD), that leads to a Bad Changeset on the client and hence the data cannot be merged and Syncing of the data stops for the client.

Different Error Variations

(but not limited to)

  1. “upload is invalid: upload progress (clientVersion=698, lastIntegratedServerVersion=356) is mutually inconsistent with threshold (clientVersion=697, lastIntegratedServerVersion=357) (ProtocolErrorCode=209)”
  2. ERROR: Connection[2]: Session[2]: Failed to parse, or apply received changeset: EraseObject: Table ‘class_Organisation’ does not exist (version: 47, last_integrated_remote_version: 1, origin_file_ident: 62, timestamp: 213527383911)
  3. Failed to open realm: { message: ‘Bad changeset (DOWNLOAD)’, errorCode: 1 }
  4. {“name”:“Error”,“message”:“Bad changeset (DOWNLOAD)”,“isFatal”:true,“category”:“realm::sync::ClientError”,“code”:112,“userInfo”:{}}

What Causes a Bad Changeset and How to Resolve it?

The reasons can vary every time. The Bad Changeset occurs when you make changes that are not permitted or do not update SDK to a newer version that has fixes.

  • Schema Inconsistencies

    • Mismatch of Client Schema and Server Schema – For instance, a difference in Optional vs Required Fields
    • Destructive Schema Changes from client-side
    • Schema changes made on the client-side (but not the server-side) with development mode off
  • Partition Issues

    • Inserting data with an incorrect partition value
    • Read/Write operations that are not permitted by Realm Sync permissions
  • Continuing to access a Synced Collection after it has been dropped

  • Using the old Realm SDK version that should have been updated

The recommended way to resolve this is to prevent these inconsistencies in your code. Some helpful documentation links are

Depending on the use case you may be required to Terminate and Re-Enable Sync to fix the state of the application. Or if this is only happening for a specific device, having that client perform a client reset may solve

If you cannot limit the cause to any of this in the list, then you may be experiencing server-side inconsistency. The recommendation is to open a post on the forum with complete details of the error log.

I hope the provided information is helpful.

Please feel free to share any information that came useful to you or any different methods you used to resolve the Bad Changeset situation.

Happy Realming! :smiley:


Hi Henna,

Thanks for the post, this is helpful.

I have a question regarding performing a client reset when a “Bad changeset (UPLOAD)” occurs.
Firstly, note that I’m fixing all cases where this could happen, so it shouldn’t happen, in theory :slight_smile: But better safe than sorry.
I managed to create a simple example where the code provokes a bad upload. The realm still opens correctly upon app startup, but disconnects shortly after. Even though I pass the .discardLocal reset strategy to the realm config before the realm is opened, this error does not seem to trigger a client reset. Why so?

I find myself unable to “catch” this error, and wipe the local changes to fix this state.


1 Like

G’Day @Baptiste_Malaguti,

Glad to know that the post was helpful to you.

“Bad changeset(UPLOAD)” happens when you are uploading data in an incorrect partition or there is a schema mismatch error. The check is done server-side and an error handler can be used to catch it on the client, it may come in as clientSessionError

This error does not trigger a client reset. This error can be corrected by uploading to the correct partition and/or fixing any schema mismatch errors.

I hope this clarifies your doubts.

Please feel free to ask if you have any more questions.

Cheers, :performing_arts: