Sitelet https://github.com/flutter/flutter/pull/188812
Skip to content

[flutter_tools] Provide guided message when iOS/macOS build fails due to low minimum version - #188812

Merged
auto-submit[bot] merged 5 commits into
flutter:masterfrom
okorohelijah:fix_187855
Jul 2, 2026
Merged

[flutter_tools] Provide guided message when iOS/macOS build fails due to low minimum version#188812
auto-submit[bot] merged 5 commits into
flutter:masterfrom
okorohelijah:fix_187855

Conversation

@okorohelijah

@okorohelijah okorohelijah commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

This PR provides clear, actionable guided messages when Xcode builds fail because the target deployment version is set too low.

Fixes #187855

If you had to change anything in the flutter/tests repo, include a link to the migration guide as per the breaking change policy.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

@github-actions github-actions Bot added platform-ios iOS applications specifically tool Affects the "flutter" command-line tool. See also t: labels. platform-macos Building on or for macOS specifically a: desktop Running on desktop team-ios Owned by iOS platform team team-macos Owned by the macOS platform team labels Jun 30, 2026
@okorohelijah
okorohelijah marked this pull request as ready for review June 30, 2026 20:09
@okorohelijah
okorohelijah requested review from a team as code owners June 30, 2026 20:09
@okorohelijah okorohelijah added the CICD Run CI/CD label Jun 30, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Jun 30, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces guided error messages when the iOS or macOS deployment target is too low for Xcode, parsing the minimum required version from build outputs and providing step-by-step upgrade instructions. The review feedback suggests refactoring the macOS build output parsing to process lines incrementally rather than buffering the entire stdout in memory. Additionally, the reviewer recommends using boolean flags to track deployment target issues and handling null or unparsed versions gracefully with fallback messages to ensure robustness against future Xcode error format changes.

Comment thread packages/flutter_tools/lib/src/macos/build_macos.dart Outdated
Comment thread packages/flutter_tools/lib/src/macos/build_macos.dart
Comment thread packages/flutter_tools/lib/src/macos/build_macos.dart Outdated
Comment thread packages/flutter_tools/lib/src/macos/build_macos.dart Outdated
Comment thread packages/flutter_tools/lib/src/ios/mac.dart Outdated
Comment thread packages/flutter_tools/lib/src/ios/mac.dart
Comment thread packages/flutter_tools/lib/src/ios/mac.dart Outdated
Comment thread packages/flutter_tools/lib/src/ios/mac.dart Outdated
Comment thread packages/flutter_tools/lib/src/ios/mac.dart
Comment thread packages/flutter_tools/lib/src/ios/mac.dart
@okorohelijah
okorohelijah marked this pull request as draft June 30, 2026 20:26
@flutter-dashboard

flutter-dashboard Bot commented Jun 30, 2026

Copy link
Copy Markdown

This pull request has been changed to a draft. The currently pending flutter-gold status will not be able to resolve until a new commit is pushed or the change is marked ready for review again.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

@okorohelijah
okorohelijah marked this pull request as ready for review June 30, 2026 21:04
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Jun 30, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds detection and guided error messages when the iOS or macOS deployment target is too low during the build process, along with corresponding tests. The review feedback requests adding /// documentation comments to the newly introduced private helper methods and fields in accordance with the repository style guide.

Comment thread packages/flutter_tools/lib/src/ios/mac.dart
Comment thread packages/flutter_tools/lib/src/ios/mac.dart
Comment thread packages/flutter_tools/lib/src/ios/mac.dart
Comment thread packages/flutter_tools/lib/src/macos/build_macos.dart
@okorohelijah

okorohelijah commented Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

I intentionally omitted instructions to update the macos/Podfile or ios/Podfile from the guided error message. While CocoaPods might require this step, we are actively migrating to Swift Package Manager (SPM). Adding CocoaPods-specific steps to the CLI error message could become obsolete and confusing.

hellohuanlin
hellohuanlin reviewed Jun 30, 2026
View reviewed changes
Comment thread packages/flutter_tools/lib/src/ios/mac.dart
requiresProvisioningProfile: false,
hasProvisioningProfileIssue: false,
iOSMinDeploymentTarget: minVersion,
hasIOSMinDeploymentTargetIssue: true,

@hellohuanlin hellohuanlin Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why true here? I assume what we wanna do is to compare the mini deployment target to the minimum that flutter supports?

@okorohelijah okorohelijah Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are setting true here because this code only runs when processing errors from a failed xcodebuild run (via xcresult). If IPHONEOS_DEPLOYMENT_TARGET is in the error message, Xcode has already done the comparison, determined the target is too low, and failed the build. We aren't doing the comparison ourselves, we are just intercepting the Xcode error to display a helpful, guided message to the user with steps to fix it in the Xcode UI.

@hellohuanlin hellohuanlin Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you give an example of the actual error message?

@okorohelijah okorohelijah Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

macOS: error: The macOS deployment target 'MACOSX_DEPLOYMENT_TARGET' is set to 10.11, but the range of supported deployment target versions is is 12.0 to 27.0.x. (in target 'Runner' from project 'Runner')

iOS: error: The iOS deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 13.0, but the range of supported deployment target versions is 15.0 to 27.0.x.
/Users/okorohelijah/development/reproductions/repro_187855/ios/Runner.xcodeproj

Instead of xcode UI, we can also tell the developer to update the project.pbxproj but that can be massive, and highly sensitive to syntax errors

@hellohuanlin hellohuanlin Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's check for sentence ("the ... deployment target ... is set to ..., but the range of supported deployment target version is ...")

@okorohelijah okorohelijah Jul 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

@okorohelijah okorohelijah added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 1, 2026
@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 1, 2026
@auto-submit

auto-submit Bot commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/188812, because - The status or check suite Tree_analyze has failed. Please fix the issues identified (or deflake) before re-applying this label.

@okorohelijah okorohelijah removed the CICD Run CI/CD label Jul 1, 2026
@okorohelijah okorohelijah added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App and removed CICD Run CI/CD labels Jul 2, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Jul 2, 2026
Merged via the queue into flutter:master with commit 8d2cde3 Jul 2, 2026
158 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 2, 2026
This was referenced Jul 2, 2026
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Jul 8, 2026
@engine-flutter-autoroll
Manual roll Flutter from ca9f874f5284 to 6995038d96ef (44 revisions) (#…
effd3a0 
…12135)

Manual roll Flutter from ca9f874f5284 to 6995038d96ef (44 revisions)

Manual roll requested by stuartmorgan@google.com

flutter/flutter@ca9f874...6995038

2026-07-03 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from sx_eN0J_f2BV6jqjW... to Jr08vyeibMSv3Oxst... (flutter/flutter#188946)
2026-07-03 engine-flutter-autoroll@skia.org Roll Packages from 420e135 to 2fbe873 (1 revision) (flutter/flutter#188945)
2026-07-03 engine-flutter-autoroll@skia.org Roll Dart SDK from 786212a2ce0d to 1f9a08ce0638 (4 revisions) (flutter/flutter#188944)
2026-07-03 engine-flutter-autoroll@skia.org Roll Skia from 5358ab75b840 to 919956953af6 (7 revisions) (flutter/flutter#188943)
2026-07-02 j.ihlas@betclicgroup.com [Windows] Keep regular windows in place when another is activated (flutter/flutter#188016)
2026-07-02 okorohelijah@google.com [flutter_tools] Provide guided message when iOS/macOS build fails due to low minimum version (flutter/flutter#188812)
2026-07-02 bdero@google.com [Flutter GPU] Load a ShaderLibrary from shader bundle bytes (flutter/flutter#188596)
2026-07-02 dacoharkes@google.com [tool] Enable record_use experiment by default on all channels (flutter/flutter#188887)
2026-07-02 engine-flutter-autoroll@skia.org Roll Packages from e742106 to 420e135 (13 revisions) (flutter/flutter#188916)
2026-07-02 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from I2h2eXk06RrA3pIG2... to sx_eN0J_f2BV6jqjW... (flutter/flutter#188915)
2026-07-02 256906086+mvincentong@users.noreply.github.com Clarify layout callback debug flag docs (flutter/flutter#186879)
2026-07-02 engine-flutter-autoroll@skia.org Roll Skia from 0c4faca350cc to 5358ab75b840 (2 revisions) (flutter/flutter#188899)
2026-07-02 engine-flutter-autoroll@skia.org Roll Dart SDK from e47361c7fe9a to 786212a2ce0d (2 revisions) (flutter/flutter#188898)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 0fc8ba72e802 to 0c4faca350cc (2 revisions) (flutter/flutter#188886)
2026-07-01 robert.ancell@canonical.com Hide draft PRs from the triage list (flutter/flutter#188885)
2026-07-01 47866232+chunhtai@users.noreply.github.com Stricten isSemantics and matchesSemantics children mismatch check (flutter/flutter#188827)
2026-07-01 jesswon@google.com [AGP 9] Support Enabling Built-in Kotlin (flutter/flutter#188543)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from d19e557ac317 to 0fc8ba72e802 (4 revisions) (flutter/flutter#188879)
2026-07-01 bkonyi@google.com [ci] Increase test timeout for Mac_x64 build_tests shards (flutter/flutter#188804)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from bd4ae38ca3bb to d19e557ac317 (1 revision) (flutter/flutter#188865)
2026-07-01 engine-flutter-autoroll@skia.org Roll Dart SDK from 26d723eb89af to e47361c7fe9a (5 revisions) (flutter/flutter#188864)
2026-07-01 katelovett@google.com Update triage links for material_ui and cupertino_ui --> Design triage (flutter/flutter#188567)
2026-07-01 flar@google.com [Impeller] Share a single ContextGLES among all PlaygroundImplGLES (flutter/flutter#188080)
2026-07-01 homobonus-luca@hotmail.it Use null-aware elements in dev/devicelab/lib/integration_tests.dart (flutter/flutter#187852)
2026-07-01 engine-flutter-autoroll@skia.org Roll Packages from 274ed3e to e742106 (18 revisions) (flutter/flutter#188863)
2026-07-01 116356835+AbdeMohlbi@users.noreply.github.com Add android 17 to embedding (flutter/flutter#187965)
2026-07-01 47866232+chunhtai@users.noreply.github.com Adds semantics role check to isSemantics and matchesSemantics (flutter/flutter#188825)
2026-07-01 rmacnak@google.com Roll Dart SDK from e1bdb9ce3327 to 26d723eb89af (3 revisions) (flutter/flutter#188795)
2026-07-01 zhongliu88889@gmail.com [web] Apply autocapitalize to text editing elements (flutter/flutter#188351)
2026-07-01 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from RymJjIj7dd5vQ3Cnh... to I2h2eXk06RrA3pIG2... (flutter/flutter#188852)
2026-07-01 bdero@google.com [Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size (flutter/flutter#188601)
2026-07-01 codedoctor@linwood.dev Improve stylus support on linux (flutter/flutter#186831)
2026-07-01 matt.boetger@gmail.com Resolve issue  Catch am start failures with 'Error type' and prevent hang (flutter/flutter#187196)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from ef178c9898af to bd4ae38ca3bb (3 revisions) (flutter/flutter#188834)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 3ac99be47229 to ef178c9898af (3 revisions) (flutter/flutter#188831)
2026-07-01 31859944+LongCatIsLooong@users.noreply.github.com Add a macosArm64Only feature flag (flutter/flutter#188598)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 15302f1625b2 to 3ac99be47229 (1 revision) (flutter/flutter#188819)
2026-07-01 bkonyi@google.com [flutter_tools] Track asset transformer dependencies for hot reload (Reland #187947) (flutter/flutter#188808)
2026-06-30 737941+loic-sharma@users.noreply.github.com Add TapRegion samples (flutter/flutter#188685)
2026-06-30 31859944+LongCatIsLooong@users.noreply.github.com Print a warning in `flutter doctor` when running on Intel Macs (flutter/flutter#188760)
2026-06-30 zhongliu88889@gmail.com [framework] Keep scrollable semantics role stable (flutter/flutter#187963)
2026-06-30 1961493+harryterkelsen@users.noreply.github.com feat(skills): Add shepherd-prs skill for managing approved external contributor PRs (flutter/flutter#188534)
2026-06-30 engine-flutter-autoroll@skia.org Roll Skia from 71947c4110b0 to 15302f1625b2 (17 revisions) (flutter/flutter#188815)
2026-06-30 bkonyi@google.com [Tool] Run re-entrant upgrade in original CWD (flutter/flutter#188794)
...
kalyujniy pushed a commit to brickit-app/camera that referenced this pull request Jul 8, 2026
@engine-flutter-autoroll @kalyujniy
Manual roll Flutter from ca9f874f5284 to 6995038d96ef (44 revisions) (f…
9cf24cd 
…lutter#12135)

Manual roll Flutter from ca9f874f5284 to 6995038d96ef (44 revisions)

Manual roll requested by stuartmorgan@google.com

flutter/flutter@ca9f874...6995038

2026-07-03 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from sx_eN0J_f2BV6jqjW... to Jr08vyeibMSv3Oxst... (flutter/flutter#188946)
2026-07-03 engine-flutter-autoroll@skia.org Roll Packages from 420e135 to 2fbe873 (1 revision) (flutter/flutter#188945)
2026-07-03 engine-flutter-autoroll@skia.org Roll Dart SDK from 786212a2ce0d to 1f9a08ce0638 (4 revisions) (flutter/flutter#188944)
2026-07-03 engine-flutter-autoroll@skia.org Roll Skia from 5358ab75b840 to 919956953af6 (7 revisions) (flutter/flutter#188943)
2026-07-02 j.ihlas@betclicgroup.com [Windows] Keep regular windows in place when another is activated (flutter/flutter#188016)
2026-07-02 okorohelijah@google.com [flutter_tools] Provide guided message when iOS/macOS build fails due to low minimum version (flutter/flutter#188812)
2026-07-02 bdero@google.com [Flutter GPU] Load a ShaderLibrary from shader bundle bytes (flutter/flutter#188596)
2026-07-02 dacoharkes@google.com [tool] Enable record_use experiment by default on all channels (flutter/flutter#188887)
2026-07-02 engine-flutter-autoroll@skia.org Roll Packages from e742106 to 420e135 (13 revisions) (flutter/flutter#188916)
2026-07-02 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from I2h2eXk06RrA3pIG2... to sx_eN0J_f2BV6jqjW... (flutter/flutter#188915)
2026-07-02 256906086+mvincentong@users.noreply.github.com Clarify layout callback debug flag docs (flutter/flutter#186879)
2026-07-02 engine-flutter-autoroll@skia.org Roll Skia from 0c4faca350cc to 5358ab75b840 (2 revisions) (flutter/flutter#188899)
2026-07-02 engine-flutter-autoroll@skia.org Roll Dart SDK from e47361c7fe9a to 786212a2ce0d (2 revisions) (flutter/flutter#188898)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 0fc8ba72e802 to 0c4faca350cc (2 revisions) (flutter/flutter#188886)
2026-07-01 robert.ancell@canonical.com Hide draft PRs from the triage list (flutter/flutter#188885)
2026-07-01 47866232+chunhtai@users.noreply.github.com Stricten isSemantics and matchesSemantics children mismatch check (flutter/flutter#188827)
2026-07-01 jesswon@google.com [AGP 9] Support Enabling Built-in Kotlin (flutter/flutter#188543)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from d19e557ac317 to 0fc8ba72e802 (4 revisions) (flutter/flutter#188879)
2026-07-01 bkonyi@google.com [ci] Increase test timeout for Mac_x64 build_tests shards (flutter/flutter#188804)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from bd4ae38ca3bb to d19e557ac317 (1 revision) (flutter/flutter#188865)
2026-07-01 engine-flutter-autoroll@skia.org Roll Dart SDK from 26d723eb89af to e47361c7fe9a (5 revisions) (flutter/flutter#188864)
2026-07-01 katelovett@google.com Update triage links for material_ui and cupertino_ui --> Design triage (flutter/flutter#188567)
2026-07-01 flar@google.com [Impeller] Share a single ContextGLES among all PlaygroundImplGLES (flutter/flutter#188080)
2026-07-01 homobonus-luca@hotmail.it Use null-aware elements in dev/devicelab/lib/integration_tests.dart (flutter/flutter#187852)
2026-07-01 engine-flutter-autoroll@skia.org Roll Packages from 274ed3e to e742106 (18 revisions) (flutter/flutter#188863)
2026-07-01 116356835+AbdeMohlbi@users.noreply.github.com Add android 17 to embedding (flutter/flutter#187965)
2026-07-01 47866232+chunhtai@users.noreply.github.com Adds semantics role check to isSemantics and matchesSemantics (flutter/flutter#188825)
2026-07-01 rmacnak@google.com Roll Dart SDK from e1bdb9ce3327 to 26d723eb89af (3 revisions) (flutter/flutter#188795)
2026-07-01 zhongliu88889@gmail.com [web] Apply autocapitalize to text editing elements (flutter/flutter#188351)
2026-07-01 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from RymJjIj7dd5vQ3Cnh... to I2h2eXk06RrA3pIG2... (flutter/flutter#188852)
2026-07-01 bdero@google.com [Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size (flutter/flutter#188601)
2026-07-01 codedoctor@linwood.dev Improve stylus support on linux (flutter/flutter#186831)
2026-07-01 matt.boetger@gmail.com Resolve issue  Catch am start failures with 'Error type' and prevent hang (flutter/flutter#187196)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from ef178c9898af to bd4ae38ca3bb (3 revisions) (flutter/flutter#188834)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 3ac99be47229 to ef178c9898af (3 revisions) (flutter/flutter#188831)
2026-07-01 31859944+LongCatIsLooong@users.noreply.github.com Add a macosArm64Only feature flag (flutter/flutter#188598)
2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 15302f1625b2 to 3ac99be47229 (1 revision) (flutter/flutter#188819)
2026-07-01 bkonyi@google.com [flutter_tools] Track asset transformer dependencies for hot reload (Reland #187947) (flutter/flutter#188808)
2026-06-30 737941+loic-sharma@users.noreply.github.com Add TapRegion samples (flutter/flutter#188685)
2026-06-30 31859944+LongCatIsLooong@users.noreply.github.com Print a warning in `flutter doctor` when running on Intel Macs (flutter/flutter#188760)
2026-06-30 zhongliu88889@gmail.com [framework] Keep scrollable semantics role stable (flutter/flutter#187963)
2026-06-30 1961493+harryterkelsen@users.noreply.github.com feat(skills): Add shepherd-prs skill for managing approved external contributor PRs (flutter/flutter#188534)
2026-06-30 engine-flutter-autoroll@skia.org Roll Skia from 71947c4110b0 to 15302f1625b2 (17 revisions) (flutter/flutter#188815)
2026-06-30 bkonyi@google.com [Tool] Run re-entrant upgrade in original CWD (flutter/flutter#188794)
...
@Piinks Piinks mentioned this pull request Jul 10, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hellohuanlin hellohuanlin hellohuanlin approved these changes
@vashworth vashworth Awaiting requested review from vashworth
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

a: desktop Running on desktop CICD Run CI/CD platform-ios iOS applications specifically platform-macos Building on or for macOS specifically team-ios Owned by iOS platform team team-macos Owned by the macOS platform team tool Affects the "flutter" command-line tool. See also t: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[iOS/macOS] Provide a guided message when build fails due to too low minimum version

2 participants

@okorohelijah @hellohuanlin