FLUTTER_BUILD_DIR environment variable - default to 'build' on macos by WillCallahan · Pull Request #180251 · flutter/flutter

WillCallahan · 2025-12-24T03:17:06Z

This PR fixes an issue where the FLUTTER_BUILD_DIR environment variable is not defaulted for macOS builds, which can cause build failures.

When building a Flutter app for macOS, parts of the build process may rely on the FLUTTER_BUILD_DIR environment variable. If this variable is not set, the build can fail with a null-pointer exception. This change ensures that FLUTTER_BUILD_DIR is always defaulted to "build" if it is not set. This is done by creating a mutable copy of the environment in the xcode_backend.dart script and setting the default value there.

This change brings the macOS build behavior in line with the iOS build process, which already has similar logic. The following files provide evidence that "build" is the correct default:

https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/ios/xcode_build_settings.dart#L174 uses getBuildDirectory(), which defaults to "build" (see https://github.com/flutter/flutter/blob/master/packages/flutter_tools/lib/src/build_info.dart#L863-L875).
https://github.com/flutter/flutter/blob/master/packages/flutter_tools/test/commands.shard/hermetic/build_macos_test.dart#L526 explicitly sets FLUTTER_BUILD_DIR=build.

Issues

This PR Closes Descriptive log on Flutter build when FLUTTER_BUILD_DIR environment variable isn't configured. #140845. Both a warning message is logged and a default value is used.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported. (This is NOT APPLICABLE)
All existing and new tests are passing.

jmagman

Thanks for your contribution @WillCallahan!

FLUTTER_BUILD_DIR should always be set in the Generated.xcconfig, for macOS as well as iOS. Despite the path,

flutter/packages/flutter_tools/lib/src/ios/xcode_build_settings.dart

Line 174 in c00f050

    
           xcodeBuildSettings.add('FLUTTER_BUILD_DIR=${buildDirOverride ?? getBuildDirectory()}');

actually is already called for macOS:

flutter/packages/flutter_tools/lib/src/macos/build_macos.dart

Line 149 in c00f050

await updateGeneratedXcodeProperties(

It would be better to diagnose why the xcconfig isn't hooked up in the project. For a newly flutter created project, it is. It sets other things beside FLUTTER_BUILD_DIR, so this is just hiding a larger problem.

Do you have flavors set up? Are the configurations set up correctly in Xcode?

If it's not set, it may be appropriate to fail with an actionable error message, instead of continuing in a bad state as this PR does.

flutter/packages/flutter_tools/bin/xcode_backend.dart

Lines 239 to 251 in c00f050

    
           echoError('========================================================================'); 
        
           echoError('ERROR: Unknown FLUTTER_BUILD_MODE: $buildMode.'); 
        
           echoError("Valid values are 'Debug', 'Profile', or 'Release' (case insensitive)."); 
        
           echoError('This is controlled by the FLUTTER_BUILD_MODE environment variable.'); 
        
           echoError('If that is not set, the CONFIGURATION environment variable is used.'); 
        
           echoError(''); 
        
           echoError('You can fix this by either adding an appropriately named build'); 
        
           echoError('configuration, or adding an appropriate value for FLUTTER_BUILD_MODE to the'); 
        
           echoError( 
        
             '.xcconfig file for the current build configuration (${environment['CONFIGURATION']}).', 
        
           ); 
        
           echoError('========================================================================'); 
        
           exitApp(-1);

WillCallahan · 2026-01-08T16:33:22Z

Ahh, I see; I performed a flutter upgrade and am missing this configuration. I will update this code so that we get a more descriptive exception message with how to fix it.

Jenn said so

jmagman · 2026-01-22T20:33:32Z

Ahh, I see; I performed a flutter upgrade and am missing this configuration. I will update this code so that we get a more descriptive exception message with how to fix it.

That shouldn't be impacted by a flutter upgrade. Are you able to go back through your git history and see when it was removed? I am still not in favor of falling back to build for only one variable when the entire xcconfig isn't hooked up, you're going to run into all kinds of other problems. For example, your app version won't reflect your pubspec version, etc.

If we want to do this, it should be to hard-fail if an expected variable from the Generated.xcconfig isn't found, not do a soft fallback for only one of the variables, and print instructions or a link to instructions for how to hook it back up in the Xcode project.

okorohelijah · 2026-02-05T22:37:05Z

@WillCallahan From Triage: We're putting this in draft. Please feel free to mark as ready for review when you want us to look at it again!

flutter-dashboard · 2026-02-05T22:41:03Z

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.

Piinks · 2026-04-06T21:44:05Z

Hey there @WillCallahan, is this a change you would like to continue working on?

Hari-07 · 2026-06-03T10:56:16Z

I can get this across the finish line if @WillCallahan isn't planning to

Piinks · 2026-06-03T15:25:42Z

Thanks @Hari-07! I am going to close this since we have not heard back. Please feel free to pick it up if you would like!

FLUTTER_BUILD_DIR environment variable - default to 'build' on macos

c985566

github-actions Bot added tool Affects the "flutter" command-line tool. See also t: labels. team-ios Owned by iOS platform team labels Dec 24, 2025

Added Test - FLUTTER_BUILD_DIR is defaulted when not set

712433d

WillCallahan marked this pull request as ready for review December 24, 2025 03:24

WillCallahan requested a review from a team as a code owner December 24, 2025 03:24

WillCallahan added 2 commits December 29, 2025 13:00

Merge branch 'flutter:master' into fix/FLUTTER_BUILD_DIR

ade334b

Merge branch 'master' into fix/FLUTTER_BUILD_DIR

2e88ab7

okorohelijah requested a review from jmagman January 2, 2026 22:32

jmagman previously requested changes Jan 2, 2026

View reviewed changes

vashworth requested review from jmagman, okorohelijah and vashworth and removed request for jmagman January 8, 2026 22:39

okorohelijah marked this pull request as draft February 5, 2026 22:37

Piinks closed this Jun 3, 2026

Hari-07 mentioned this pull request Jun 10, 2026

Add validation for required fields during xcodebuild #187772

Merged

10 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

FLUTTER_BUILD_DIR environment variable - default to 'build' on macos#180251

FLUTTER_BUILD_DIR environment variable - default to 'build' on macos#180251
WillCallahan wants to merge 4 commits into
flutter:masterfrom
WillCallahan:fix/FLUTTER_BUILD_DIR

WillCallahan commented Dec 24, 2025 •

edited

Loading

Uh oh!

jmagman left a comment

Uh oh!

WillCallahan commented Jan 8, 2026

Uh oh!

jmagman commented Jan 22, 2026

Uh oh!

okorohelijah commented Feb 5, 2026

Uh oh!

flutter-dashboard Bot commented Feb 5, 2026

Uh oh!

Piinks commented Apr 6, 2026

Uh oh!

Hari-07 commented Jun 3, 2026

Uh oh!

Piinks commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	echoError('========================================================================');
	echoError('ERROR: Unknown FLUTTER_BUILD_MODE: $buildMode.');
	echoError("Valid values are 'Debug', 'Profile', or 'Release' (case insensitive).");
	echoError('This is controlled by the FLUTTER_BUILD_MODE environment variable.');
	echoError('If that is not set, the CONFIGURATION environment variable is used.');
	echoError('');
	echoError('You can fix this by either adding an appropriately named build');
	echoError('configuration, or adding an appropriate value for FLUTTER_BUILD_MODE to the');
	echoError(
	'.xcconfig file for the current build configuration (${environment['CONFIGURATION']}).',
	);
	echoError('========================================================================');
	exitApp(-1);

Uh oh!

Conversation

WillCallahan commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issues

Pre-launch Checklist

Uh oh!

jmagman left a comment

Choose a reason for hiding this comment

Uh oh!

WillCallahan commented Jan 8, 2026

Uh oh!

jmagman commented Jan 22, 2026

Uh oh!

okorohelijah commented Feb 5, 2026

Uh oh!

flutter-dashboard Bot commented Feb 5, 2026

Uh oh!

Piinks commented Apr 6, 2026

Uh oh!

Hari-07 commented Jun 3, 2026

Uh oh!

Piinks commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

WillCallahan commented Dec 24, 2025 •

edited

Loading