Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

Resolving iOS Application Freezes or Crashes During RTC SDK Initialization

Updated

Issue Description

When launching an iOS application or initializing the RTC Engine right before entering a channel, the application may become unresponsive or unexpectedly crash. While no explicit SDK error callback is thrown, system crash logs or performance monitors report main thread hangs, timeouts, or thread execution blocked inside agora::rtc::RtcEngine::initializeEx.

 

Platform and SDK Context

  • Operating System: iOS

  • SDK Component: Agora RTC SDK

  • Target Diagnostic Error/Trace: Main thread stack trace blocked on initialize / initializeEx

     

     

Root Cause Analysis

This issue occurs because the application initializes the Agora RTC engine (sharedEngineWithConfig / initializeEx) directly on the main UI thread just before joining a channel. Executing synchronous initialization on the main thread blocks UI execution. On certain devices—particularly when using older SDK versions with unoptimized initialization routines—this results in application freezes or unexpected crashes.

During initialization, the SDK executes synchronous tasks such as hardware probing, dynamic library loading, and media subsystem setup. Calling these on DispatchQueue.main directly blocks the iOS Main Run Loop. If the main thread remains unresponsive beyond the system threshold, the iOS Watchdog mechanism forcibly terminates the application process (often generating a 0x8badf00d termination code), which appears in telemetry as a crash or main thread hang.

 

Solution and Resolution Steps

  1. Dispatch Initialization to a Background Thread

    Move the sharedEngineWithConfig or initializeEx invocation from the UI thread to an asynchronous global background queue (GCD).

     

  2. Pre-Initialize Engine During Application Startup

    Avoid lazy-loading the RTC Engine synchronously right when the user taps "Join Room". Instead, pre-initialize the engine asynchronously during App AppDelegate/SceneDelegate startup or background view loading to eliminate pre-call latency.

     

  3. Upgrade to SDK v4.5.0 or Later

    Upgrade your application to Agora RTC SDK v4.5.0 or newer. Modern SDK releases feature optimized background startup sequences and non-blocking sub-module registration to minimize initialization duration.

 

Prevention and Best Practice

To ensure stable performance and prevent UI thread blocking across iOS releases:

  • Strict Threading Policy: Never execute synchronous RTC Engine lifecycle operations, such as engine instantiation, heavy plugin registration, or channel cleanup, on the main thread.

  • Integrate ANR & Crash Monitoring: Utilize APM tools, such as Xcode Metrics, Firebase Performance Monitoring, to monitor main thread latency and detect Watchdog timeouts early in test cycles.

  • Pre-warm Media Subsystems: Pre-initialize engine instances asynchronously prior to active call workflows to deliver near-instant channel joins without UI stutter.