[CBL-6791] Starting a Live Query in the Background May Crash the App

Product: Couchbase Lite
Component: couchbase-lite
Issue Link: CBL-6791
Affects Version: 3.2.x
Fix Version: 3.3.0

Summary

• CBL-6791 addresses a crash that occurs when starting a Couchbase Lite Live Query while the application is running in the background.
• The core problem was a race condition during app backgrounding, caused by exceptions not being caught inside a noexcept-marked native function for starting Live Queries in the background.
• This issue is hard to reproduce locally, but has been confirmed from crash logs (SIGABRT in CBLDatabase safeBlock:).

Symptoms 

• App crashes intermittently during background execution, typically about 1% of launches, with a higher frequency in larger deployments.

Triggers

• Starting a Live Query or adding a Live Query observer while the app is in the background.
• Live query creation is permitted from any thread/context and may execute asynchronously.
• Replicator state (paused/stopped) is unrelated to the crash.

Verification

• Crash logs indicate the fault in CBLDatabase safeBlock and/or CBLQueryObserver start and exception type as SIGABRT. For Example:

Thread 36 Crashed:
0   libsystem_kernel.dylib           0x00000001ee34d1d4 0x1ee341000 + 49620
1   libsystem_c.dylib                0x00000001a5d3fad8 0x1a5cc8000 + 490200
2   libc++abi.dylib                  0x00000002262cd5b8 __cxxabiv1::__aligned_malloc_with_fallback(unsigned long) (libc++abi.dylib)
3   libc++abi.dylib                  0x00000002262bbb90 demangling_terminate_handler() (libc++abi.dylib)
4   libobjc.A.dylib                  0x000000019b29ee24 0x19b26c000 + 208420
5   CouchbaseLiteSwift               0x0000000117c64120 fleece::Backtrace::installTerminateHandler(std::__1::function<void (std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&)>)::$_1::operator()() const::'lambda'()::__invoke() (Backtrace.cc:414)
6   libc++abi.dylib                  0x00000002262cc87c std::__terminate(void (*)()) (libc++abi.dylib)
7   libc++abi.dylib                  0x00000002262cc820 std::terminate() (libc++abi.dylib)
8   CouchbaseLiteSwift               0x0000000117aca75c -[CBLDatabase safeBlock:] (CBLDatabase.mm:0)
9   CouchbaseLiteSwift               0x0000000117ad802c -[CBLQueryObserver start] (CBLQueryObserver.m:75)
10  CouchbaseLiteSwift               0x0000000117ad1690 -[CBLQuery addChangeListenerWithQueue:listener:] (CBLQuery.mm:294)
11  CouchbaseLiteSwift               0x0000000117a2b388 Query.addChangeListener(withQueue:_:) (Query.swift:103)
12  Database                         0x0000000109d91158 $s12Database14DatabaseResultC16addQueryObserver33_D692713274F138CG4477741F690H057BMMyyAyyZbvbU_ (Results.swift:398)

• Review might also show similar symptoms to CBL-6676.
• Also, check the code: the query observer addition or live query creation might be made inside a dispatch-protected lock, but still be triggered while backgrounded.

Workarounds

• The permanent fix is included in Couchbase Lite 3.3.0, where exceptions are caught, and a warning is logged rather than crashing the app.
• Until 3.3.0 can be adopted, application-side state checks provide the safest workaround for production applications.
  • Implement an app state check in the logic to ensure live queries or observers are only added when the app is in the foreground.
  • Resume live-query/observer addition when returning to the foreground.
  • Ignore and log exceptions where this race occurs.