Repository navigation
[stable] [flutter_tools] Exit cleanly when Windows path exceeds MAX_PATH (OS Error 206) - #195073
Merged
auto-submit[bot] merged 1 commit intoOct 26, 2026
Conversation
…rror 206) (flutter#194867) When a Flutter project, SDK, or subprocess command path on Windows exceeds `MAX_PATH` (260 characters), Win32 process and file operations fail with OS error code `206` (`ERROR_FILENAME_EXCED_RANGE`: `The filename or extension is too long`). Previously, `_handleWindowsException` in `error_handling_io.dart` did not recognize error code `206`, causing `ErrorHandlingProcessManager` and `ErrorHandlingFileSystem` to rethrow an unhandled `ProcessPackageException` or `FileSystemException` and trigger a crash report. Add `kFilenameExcedRange = 206` to `_handleWindowsException` so operations failing with error code `206` exit cleanly with a `ToolExit` instructing the user to move the Flutter SDK and/or project to a shorter path or enable long paths on Windows. ```text Unhandled exception: ProcessPackageException: ProcessException: The filename or extension is too long Command: C:\Users\User\AppData\Local\Temp\... ``` ```text Flutter failed to run "C:\Users\User\AppData\Local\Temp\...". The filename or extension is too long. ProcessException: The filename or extension is too long Command: C:\Users\User\AppData\Local\Temp\... Please consider moving the Flutter SDK and/or project to a shorter path, or enabling long paths on Windows. ``` Fixes flutter#194570
|
This pull request was opened from and to a release candidate branch. This should only be done as part of the official Flutter release process. If you are attempting to make a regular contribution to the Flutter project, please close this PR and follow the instructions at Tree Hygiene for detailed instructions on contributing to Flutter. Reviewers: Use caution before merging pull requests to release branches. Ensure the proper procedure has been followed. |
github-actions
Bot
added
the
tool
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces handling for the Windows error code 206 (filename or extension too long) by displaying a helpful error message that suggests moving the project to a shorter path or enabling long paths. It also adds comprehensive unit tests to verify this behavior for both file system operations and process execution. Feedback is provided to use single quotes instead of double quotes within string interpolation to adhere to the Effective Dart style guide.
Comment on lines
+1472
to
+1476
| kFilenameExcedRange => | ||
| '${message != null ? "$message. " : ""}The filename or extension is too long.\n' | ||
| '$e\n' | ||
| 'Please consider moving the Flutter SDK and/or project to a shorter path, ' | ||
| 'or enabling long paths on Windows.', |
Contributor
There was a problem hiding this comment.
According to the Dart style guide (Effective Dart: Style), single quotes are preferred for string literals. Using single quotes inside the string interpolation is more consistent with the rest of the codebase.
Suggested change
| kFilenameExcedRange => | |
| '${message != null ? "$message. " : ""}The filename or extension is too long.\n' | |
| '$e\n' | |
| 'Please consider moving the Flutter SDK and/or project to a shorter path, ' | |
| 'or enabling long paths on Windows.', | |
| kFilenameExcedRange => | |
| '${message != null ? '$message. ' : ''}The filename or extension is too long.\n' | |
| '$e\n' | |
| 'Please consider moving the Flutter SDK and/or project to a shorter path, ' | |
| 'or enabling long paths on Windows.', |
References
- Effective Dart: Style recommends preferring single quotes for string literals. (link)
reidbaker
approved these changes
Oct 26, 2026
reidbaker
added
the
autosubmit
auto-submit
Bot
merged commit Oct 26, 2026
8d765b9
into
flutter:flutter-3.47-candidate.0
12 checks passed
This was referenced Oct 28, 2026
auto-submit Bot
pushed a commit
that referenced
this pull request
Oct 29, 2026
Adds CHANGELOG.md entries for the 3.47.9 stable hotfix (#195073, #194959, #195015). CI-only cherry-picks are omitted. Tracker: #195427 ### Edits to cherry-pick changelog descriptions - #195073 and #195015: used verbatim from the cherry-pick PR's "Changelog Description". - #194959 (@bkonyi): **edited** to follow [Hotfix Documentation Best Practices](https://github.com/flutter/flutter/blob/main/docs/releases/Hotfix-Documentation-Best-Practices.md) (describe the state prior to the fix): - Original: "When running `flutter test` in pub workspaces, monorepos, or symlinked directories, fix a StateError crash during native assets compilation by falling back to appName matching." - Changelog: "When running `flutter test` in pub workspaces, monorepos, or symlinked directories on any platform, native assets compilation crashed with a `StateError`." - Changes: rewrote as the pre-fix behavior, added "on any platform", dropped the implementation detail ("falling back to appName matching"). @bkonyi FYI — please let us know if the edited wording for #194959 looks right.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request is created by automatic cherry pick workflow
Please fill in the form below, and a flutter domain expert will evaluate this cherry pick request.
Issue Link:
#194570
Impact Description:
When a Flutter project, SDK, or subprocess command path on Windows exceeds
MAX_PATH(260 characters), Win32 process and file operations fail with OS error code206(ERROR_FILENAME_EXCED_RANGE:The filename or extension is too long). Previously,_handleWindowsExceptioninerror_handling_io.dartdid not recognize error code206, causingErrorHandlingProcessManagerandErrorHandlingFileSystemto rethrow an unhandledProcessPackageExceptionorFileSystemExceptionand trigger a crash report (#10 top crasher in Flutter 3.47.7). This change handles error code206and exits cleanly with aToolExitmessage guiding the user to move the Flutter SDK and/or project to a shorter path or enable long paths on Windows.Conflict Resolution (
stable): Resolved a trivial merge conflict in_handleWindowsException(packages/flutter_tools/lib/src/base/error_handling_io.dart) caused by error code constant ordering differences betweenflutter-3.47-candidate.0andmaster.Changelog Description:
[flutter/194570] When a path or command exceeds
MAX_PATHon Windows (OS Error 206),flutter_toolscrashed with an unhandledProcessPackageExceptionorFileSystemExceptioninstead of exiting cleanly with an actionable error message.Workaround:
Move the Flutter SDK and/or project to a shorter directory path, enable Windows Long Paths, or set
PUB_CACHE/ delete$FLUTTER_ROOT/.pub-preload-cacheif hit during initial pub cache preload.Risk:
What is the risk level of this cherry-pick?
Test Coverage:
Are you confident that your fix is well-tested by automated tests?
Validation Steps:
Run a
fluttercommand (such asflutter pub get) on Windows where a file or subprocess command fails with OS error206(ERROR_FILENAME_EXCED_RANGE), or runflutter test test/general.shard/base/error_handling_io_test.dart, and verify thatflutter_toolsexits cleanly with aToolExitmessage rather than an unhandled exception crash.