Flutter iOS Flavors: Align Scheme, Configuration and Bundle Identifier

A Flutter iOS flavor depends on the selected Xcode scheme and the configuration attached to its Archive action. A production scheme can run successfully in debug mode yet archive with the wrong configuration. Trace the scheme-to-archive chain before changing signing credentials.

Flutter's iOS flavor guide, checked October 8, 2026, documents shared schemes, configuration naming and Flutter configuration-file inheritance. This is an audit of that mapping, not a second Android flavor setup tutorial.

Write the mapping you expect#

Record the scheme, Archive configuration, bundle identifier, Flutter entry point and export method for the intended release. Keep staging and production records separate.

Scheme: production
Archive configuration: Release-production
Expected bundle ID: com.example.catalog
Flutter entry point: lib/main_production.dart
Export method: the team's intended distribution method

This is a hypothetical contract. If your project uses different names, verify those names rather than renaming a working project to match the example.

Confirm CI can see the scheme#

List the workspace's schemes through Xcode's supported tools:

xcodebuild -list -workspace ios/Runner.xcworkspace

Adjust the workspace path for your repository. Compare the result with the scheme selected by CI. Flutter's guide says schemes must be shared for flavors to work; a scheme existing only in a developer's personal Xcode state is not enough.

Check the committed scheme files and the Archive action. Do not infer Archive behavior from the Run action: they can use different configurations.

Follow configuration inheritance#

Flutter's configuration instructions specify Flutter's Debug.xcconfig and Release.xcconfig as the bases, rather than directly basing custom configurations on a Pods configuration. Profile and Release normally use the Release base in its example.

Inspect your custom includes, environment overrides and native dependency configuration. For an existing CocoaPods setup, verify the Podfile's configuration mapping when adding schemes. For a Swift Package Manager setup, follow that integration's applicable configuration instead of creating a Podfile merely because an old example uses one.

The goal is to preserve Flutter's required build settings while applying the intended environment-specific values. A configuration file with the correct name can still inherit the wrong values.

Inspect resolved settings for the Archive configuration#

Use a read-only settings report, substituting your actual scheme:

xcodebuild -showBuildSettings \
  -workspace ios/Runner.xcworkspace \
  -scheme production -configuration Release-production

Inspect the bundle identifier, configuration, team and version-related settings. Keep the report internal and redact sensitive custom settings before sharing it.

If the resolved bundle identifier is wrong, correct the scheme/configuration mapping before attempting certificate rotation. A signing error may be the downstream effect of the wrong application identity.

Compare the actual archive#

Open the produced archive and check its app bundle identifier, version and build number. Confirm the export settings refer to the same intended app and distribution method. Record the archive checksum with these observations.

Then run an authorized installation smoke test for the exported build. Verify the intended environment with non-secret evidence, including any relevant push, deep-link and Firebase mappings.

Keep the correction reviewable#

Change only the mapping that evidence shows is wrong. Retain the previous configuration and the failing log for comparison. Avoid mixing a scheme correction with unrelated plugin or signing changes.

If an AI tool proposes a larger rewrite, use the generated-code review checklist. The acceptance condition is an archive with the intended identity and behavior, not simply a scheme list containing the word “production.”