When building a Flutter iOS app for App Preview, you may encounter the following error even though simulators are available on the build machine:

Last updated: July 27, 2026

Unable to find a destination matching the provided destination specifier:
{ generic:1, platform:iOS Simulator }

App Preview requires an unsigned .app built for the iOS Simulator rather than a device archive or signed IPA.

Root cause

In the affected Flutter project, the generated Xcode project was configured with:

SUPPORTED_PLATFORMS = iphoneos

This excludes iphonesimulator and causes xcodebuild to filter out simulator destinations during the build process, even though the simulators are installed on the build machine.

Solution

To successfully build the Flutter iOS app for App Preview, follow these three steps.

1. Boot a simulator before building

Boot the required simulator before running the build:

xcrun simctl boot "iPhone 17 Pro Max" || true

2. Patch the Xcode project to allow simulator builds

Modify the project configuration to include simulator support:

sed -i '' 's/SUPPORTED_PLATFORMS = iphoneos;/SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";/g' \
  ios/Runner.xcodeproj/project.pbxproj

sed -i '' 's/SDKROOT = iphoneos;/SDKROOT = iphoneos;\n\t\t\t\tSUPPORTED_PLATFORMS = "iphoneos iphonesimulator";/g' \
  ios/Runner.xcodeproj/project.pbxproj

3. Build directly with xcodebuild

Use xcodebuild instead of flutter build ios --simulator:

xcodebuild -workspace "ios/Runner.xcworkspace" \
  -scheme "Runner" \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2' \
  -configuration Debug \
  CODE_SIGN_IDENTITY="" \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGNING_ALLOWED=NO \
  -derivedDataPath ios/output

Complete workflow example

The following workflow implements the solution:

workflows:
  ios-workflow:
    name: iOS Workflow
    max_build_duration: 120
    instance_type: mac_mini_m4
    environment:
      flutter: stable
      xcode: 26.2
    scripts:
      - name: Boot simulator
        script: |
          xcrun simctl boot "iPhone 17 Pro Max" || true
      - name: Patch Xcode project for simulator support
        script: |
          sed -i '' 's/SUPPORTED_PLATFORMS = iphoneos;/SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";/g' \
            ios/Runner.xcodeproj/project.pbxproj
          sed -i '' 's/SDKROOT = iphoneos;/SDKROOT = iphoneos;\n\t\t\t\tSUPPORTED_PLATFORMS = "iphoneos iphonesimulator";/g' \
            ios/Runner.xcodeproj/project.pbxproj
      - name: Build unsigned .app for simulator
        script: |
          xcodebuild -workspace "ios/Runner.xcworkspace" \
            -scheme "Runner" \
            -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2' \
            -configuration Debug \
            CODE_SIGN_IDENTITY="" \
            CODE_SIGNING_REQUIRED=NO \
            CODE_SIGNING_ALLOWED=NO \
            -derivedDataPath ios/output
    artifacts:
      - ios/output/Build/Products/Debug-iphonesimulator/Runner.app

Recommended configuration

This solution was validated using:

instance_type: mac_mini_m4
xcode: 26.2

This configuration provides the required simulator platform and produces the unsigned .app needed for App Preview. Apple notes that builds cannot run against a simulator destination when the corresponding platform support is unavailable.

After the simulator .app is published as an artifact, the Quick Launch option should be available in App Preview.

Approaches that did not work in this case

The following approaches did not resolve the issue in the tested configuration:

  • Running flutter build ios --debug --simulator, which continued to report that no matching simulator destination could be found.

  • Passing SUPPORTED_PLATFORMS only as an xcodebuild command-line override, because destination resolution occurred before the override took effect.

  • Using a build machine or Xcode configuration that did not have the required simulator platform available.

The exact simulator name and OS version may vary depending on the Xcode version selected for the build. You can check the available simulators with:

xcrun simctl list devices available