Realm IllegalStateException: accessing managed objects across threads during sync writes

Direct Resolution

To pass data from the main thread to a background worker without triggering an IllegalStateException, you have two primary options depending on whether you need a live object or a snapshot:

• For Read-Only Access: Use object.freeze(). Frozen objects are immutable snapshots that bypass thread confinement and can be passed directly to coroutines or background threads.
• For Write Operations: Pass only the primary key (e.g., a String or Long) to the background thread. Open a new Realm instance on that thread and re-query the object using that key.

Thread Confinement Boundaries

In Realm (Kotlin SDK 1.x), thread confinement is strict and applies to the following:

• Managed Objects: Any object returned from a query is tied to the thread that executed the query.
• Live Collections: RealmResults and RealmList are also thread-confined. Passing a live list to a background worker will cause an IllegalStateException even if the originating Realm is closed.
• Realm Instances: The Realm instance itself is thread-confined. You cannot share a single Realm object across threads; each thread must call Realm.getInstance() or Realm.open() to obtain its own handle to the database.

Frozen Objects vs. Managed Objects

Feature	Managed Object	Frozen Object
Thread Confined	Yes	No
Live Updates	Yes (Auto-updating)	No (Snapshot)
Modifiable	Yes (within transaction)	No (Immutable)

Implementation Steps

1. Freeze the object on the main thread: val frozenUser = user.freeze().
2. Pass the frozen object to your background worker/coroutine.
3. Read values from the frozen object safely on the background thread.
4. Perform the write by opening a thread-local Realm instance and querying the original object by its primary key to create a "thawed" managed version for the transaction.

Verification: You can verify this by attempting to read a field from a managed object inside a Dispatchers.IO block; it will throw an IllegalStateException. Replacing that object with a frozen version will resolve the error.

Diagnostic Note: Please specify if you are using the legacy Realm Java SDK or the newer Realm Kotlin SDK (Atlas Device SDK), as the API for freezing and opening instances differs slightly between the two.