Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

Solving Flutter iOS Release Build Issues with Agora SDK Integration

Updated

Issue Description:

Users encounter a runtime error while attempting to build the release version of a Flutter iOS app using the Agora SDK. The error indicates that a necessary symbol (Iris_InitDartApiDL) is not found in the dynamic library, preventing successful app deployment.

 

Platform/SDK:

Flutter SDK version 3.32.5 (Channel stable) on macOS 15.5, targeting iOS platform. Utilizes the Agora SDK, specifically the agora_rtc_engine version 6.5.2 with dynamic linking through Iris SDK bridge.

 

Error Message:


[ERROR:flutter/runtime/dart_isolate.cc(1390)] Unhandled exception: 
Invalid argument(s): Failed to lookup symbol 'Iris_InitDartApiDL': dlsym(RTLD_DEFAULT, Iris_InitDartApiDL): symbol not found

 

Step by Step Solution:

1. Open Xcode:

Open Xcode and load the workspace file located at ios/Runner.xcworkspace.

 

2. Build Settings:

Navigate to Build Settings for the Runner target.

 

3. Modify Linker Flags:

Locate the Other Linker Flags setting and add the following linker flag:


-force_load $(PODS_ROOT)/AgoraRtcEngine_iOS/AgoraRtcKit.xcframework/ios-arm64_armv7/AgoraRtcKit.framework/AgoraRtcKit

This ensures the Iris symbols are preserved during linking.

 

4. Modify Podfile:

Modify your Podfile to include the following configuration to prevent symbol stripping:

ruby
use_frameworks! :linkage => :static

After making this change, run the following commands in the terminal:

shell
cd ios
pod deintegrate
pod install
cd ..
flutter clean
flutter build ios --release --no-tree-shake-icons

 

5. Update Release.xcconfig:

If the symbol is still not found, update Release.xcconfig by adding the following to the ios/Flutter/Release.xcconfig file:


OTHER_LDFLAGS = $(inherited) -ObjC -lc++

 

6. Verify Symbol:

Verify if the Iris_InitDartApiDL symbol exists in the compiled binary by running:

shell
cd ios/Pods/AgoraRtcEngine_iOS/AgoraRtcKit.xcframework/ios-arm64_armv7/AgoraRtcKit.framework
nm AgoraRtcKit | grep Iris_InitDartApiDL

 

Root Cause:

The issue arises from Flutter's iOS release build optimization processes, specifically tree shaking and dead code stripping, which inadvertently remove dynamically loaded symbols from the Agora SDK's Iris bridge.

 

Prevention/Best Practice:

  • Regularly consult the Flutter and Agora documentation for any updates or recommended practices regarding iOS deployment.
  • Use the flutter build ios --release --no-tree-shake-icons command to disable unnecessary code stripping during release builds.

 

Related to

Related articles