All Community
Why does my project build fail when I use the iOS simulator in Xcode 12.3 or later?
Type: Integration issues    Platform: iOS   Last Updated: 2021/01/28 20:12:41


When you integrate the Agora SDK and use an iOS simulator to build a project in Xcode 12.3 or later, you may receive the following error message:

Building for iOS Simulator, but the linked and embedded framework 'xxx.framework' was built for iOS + iOS Simulator.


Starting in Xcode 11.0, Apple recommended against using a single .framework file to bundle a binary framework or library for multiple platforms, although they still allowed it. As of Xcode 12.3, however, Apple no longer allows this; instead, you must use an .xcframework file. To support running a project on an iOS simulator, versions of the Agora SDK earlier than v3.3.0 bundle a library for multiple platforms in a .framework file, so .framework files are identified by Xcode as a prohibited configuration when you use an iOS simulator to build a project.


Solution one: Upgrade the SDK

As of v3.3.0, the Agora SDK uses .xcframework files in place of .framework files, which comply with Xcode's requirements and support running projects on iOS physical devices or iOS simulators. Agora recommends upgrading the SDK to v3.3.0 or later. See Integrate the SDK.

Solution two: Change build options

In Xcode, navigate to TARGETS > Project Name > Build Settings > Build Options menu, and set Validate Workspace as Yes.

Solution three: Create .xcframework files

For the SDK v3.0.0 to v3.2.1, Agora provides an script to create .xcframework files based on .framework files. Refer to the following steps to use this script:

  1. Create an file, and add the following code to the file:

    echo "Start building xcframework..."
    cd $AgoraIosFrameworkDir
    # Detect the SDK path
    if [ ! -d "libs" ]; then
     echo "SDK path error, please check!"
     exit 1
    cd libs/
    # Find all .framework files under the libs folder
    for file in `ls $cur_path`; do
     echo $file
     if [[ $file == *$framework_suffix* ]]; then
         frameworks="$frameworks $file"
    echo "Frameworks found:$frameworks"
    for framework in $frameworks; do
     echo "framework_name is $binary_name"
     # In the Info.plist file under the ALL_ARCHITECTURE/xxx.framework path, change the CFBundleSupportedPlatforms attribute to x86-64 or i386 only
     plutil -replace CFBundleSupportedPlatforms -json "[$supported_platforms]" ALL_ARCHITECTURE/$framework/Info.plist || exit 1
     # Remove the armv7 and arm64 architectures in the .framework file under the ALL_ARCHITECTURE folder, and keep the x86-64 or i386 architecture only
     lipo -remove armv7 ALL_ARCHITECTURE/$framework/$binary_name -output ALL_ARCHITECTURE/$framework/$binary_name
     lipo -remove arm64 ALL_ARCHITECTURE/$framework/$binary_name -output ALL_ARCHITECTURE/$framework/$binary_name
     # Use the xcodebuild command to create an .xcframework file based on the devices architecture under the libs folder and the .framework file under the ALL_ARCHITECTURE folder
     xcodebuild -create-xcframework -framework $framework -framework ALL_ARCHITECTURE/$framework -output $binary_name.xcframework
    echo "Build xcframework successfully."
  2. In Terminal, run the following command to create .xcframework files:

    // Replace the xcframework_path with the path of the script
    cd xcframework_path
    // Run the script
    // Replace the sdk_path with the path of the SDK. For example, /Users/agora/Downloads/Agora_Native_SDK_for_iOS_FULL
    sh sdk_path
  3. Navigate to your project folder, delete the .framework files, and copy the .xcframework files into the folder.

  4. In Xcode (the interface description in this article is based on Xcode 12.3), navigate to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content menu:

    1. Click - to remove .framework files.
    2. Click + > Add Other… > Add Files to add the corresponding .xcframework files. Ensure the status of these dynamic libraries is Embed & Sign.

    For example, with the Video SDK v3.2.0, after you successfully configure the project, you see the following interface:

For more information about creating an .xcframework file, see Create an XCFramework.