Skip to content

Commit 8d765b9

Browse files
authored
[stable] [flutter_tools] Exit cleanly when Windows path exceeds MAX_PATH (OS Error 206) (#195073)
This pull request is created by [automatic cherry pick workflow](https://github.com/flutter/flutter/blob/main/docs/releases/Flutter-Cherrypick-Process.md#automatically-creates-a-cherry-pick-request) 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 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 (#10 top crasher in Flutter 3.47.7). This change handles error code `206` and exits cleanly with a `ToolExit` message 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 between `flutter-3.47-candidate.0` and `master`. ### Changelog Description: [flutter/194570] When a path or command exceeds `MAX_PATH` on Windows (OS Error 206), `flutter_tools` crashed with an unhandled `ProcessPackageException` or `FileSystemException` instead 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-cache` if 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 `flutter` command (such as `flutter pub get`) on Windows where a file or subprocess command fails with OS error `206` (`ERROR_FILENAME_EXCED_RANGE`), or run `flutter test test/general.shard/base/error_handling_io_test.dart`, and verify that `flutter_tools` exits cleanly with a `ToolExit` message rather than an unhandled exception crash.
1 parent b4e3ab4 commit 8d765b9

2 files changed

Lines changed: 99 additions & 0 deletions

File tree

‎packages/flutter_tools/lib/src/base/error_handling_io.dart‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1445,6 +1445,7 @@ void _handleWindowsException(Exception e, String? message, int errorCode) {
14451445
const kDeviceFull = 112;
14461446
const kSharingViolation = 32;
14471447
const kLockViolation = 33;
1448+
const kFilenameExcedRange = 206;
14481449
const kUserMappedSectionOpened = 1224;
14491450
const kAccessDenied = 5;
14501451
const kFatalDeviceHardwareError = 483;
@@ -1468,6 +1469,11 @@ void _handleWindowsException(Exception e, String? message, int errorCode) {
14681469
'$message. The target device is full.'
14691470
'\n$e\n'
14701471
'Free up space and try again.',
1472+
kFilenameExcedRange =>
1473+
'${message != null ? "$message. " : ""}The filename or extension is too long.\n'
1474+
'$e\n'
1475+
'Please consider moving the Flutter SDK and/or project to a shorter path, '
1476+
'or enabling long paths on Windows.',
14711477
kSharingViolation || kLockViolation || kUserMappedSectionOpened =>
14721478
'$message. The file is being used by another program.'
14731479
'\n$e\n'

‎packages/flutter_tools/test/general.shard/base/error_handling_io_test.dart‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ void main() {
155155

156156
group('throws ToolExit on Windows', () {
157157
const kDeviceFull = 112;
158+
const kFilenameExcedRange = 206;
158159
const kUserMappedSectionOpened = 1224;
159160
const kUserPermissionDenied = 5;
160161
const kFatalDeviceHardwareError = 483;
@@ -414,6 +415,41 @@ void main() {
414415
throwsToolExit(message: 'The flutter tool cannot access the file or directory'),
415416
);
416417
});
418+
419+
testWithoutContext('when the filename or extension is too long', () async {
420+
final fileSystem = ErrorHandlingFileSystem(
421+
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
422+
platform: windowsPlatform,
423+
);
424+
final File file = fileSystem.file('file');
425+
426+
exceptionHandler.addError(
427+
file,
428+
FileSystemOp.write,
429+
FileSystemException('', file.path, const OSError('', kFilenameExcedRange)),
430+
);
431+
exceptionHandler.addError(
432+
file,
433+
FileSystemOp.open,
434+
FileSystemException('', file.path, const OSError('', kFilenameExcedRange)),
435+
);
436+
exceptionHandler.addError(
437+
file,
438+
FileSystemOp.create,
439+
FileSystemException('', file.path, const OSError('', kFilenameExcedRange)),
440+
);
441+
442+
const expectedMessage = 'The filename or extension is too long.';
443+
await expectLater(
444+
() => file.writeAsBytes(<int>[0]),
445+
throwsToolExit(message: expectedMessage),
446+
);
447+
await expectLater(() => file.writeAsString(''), throwsToolExit(message: expectedMessage));
448+
expect(() => file.writeAsBytesSync(<int>[0]), throwsToolExit(message: expectedMessage));
449+
expect(() => file.writeAsStringSync(''), throwsToolExit(message: expectedMessage));
450+
expect(() => file.openSync(), throwsToolExit(message: expectedMessage));
451+
expect(() => file.createSync(), throwsToolExit(message: expectedMessage));
452+
});
417453
});
418454

419455
group('throws ToolExit on Linux', () {
@@ -984,6 +1020,7 @@ Please ensure that the SDK and/or project is installed in a location that has re
9841020

9851021
group('ProcessManager on windows throws tool exit', () {
9861022
const kDeviceFull = 112;
1023+
const kFilenameExcedRange = 206;
9871024
const kUserMappedSectionOpened = 1224;
9881025
const kUserPermissionDenied = 5;
9891026
const kApplicationControlPolicyBlocked = 4551;
@@ -1184,6 +1221,62 @@ Please ensure that the SDK and/or project is installed in a location that has re
11841221
);
11851222
});
11861223

1224+
testWithoutContext('when the filename or extension is too long', () async {
1225+
final fakeProcessManager = FakeProcessManager.list(<FakeCommand>[
1226+
const FakeCommand(
1227+
command: <String>['foo', '--bar'],
1228+
exception: ProcessException(
1229+
'foo',
1230+
<String>['--bar'],
1231+
'The filename or extension is too long',
1232+
kFilenameExcedRange,
1233+
),
1234+
),
1235+
const FakeCommand(
1236+
command: <String>['foo', '--bar'],
1237+
exception: ProcessException(
1238+
'foo',
1239+
<String>['--bar'],
1240+
'The filename or extension is too long',
1241+
kFilenameExcedRange,
1242+
),
1243+
),
1244+
const FakeCommand(
1245+
command: <String>['foo', '--bar'],
1246+
exception: ProcessException(
1247+
'foo',
1248+
<String>['--bar'],
1249+
'The filename or extension is too long',
1250+
kFilenameExcedRange,
1251+
),
1252+
),
1253+
]);
1254+
1255+
final ProcessManager processManager = createProcessManager(
1256+
delegate: fakeProcessManager,
1257+
platform: windowsPlatform,
1258+
);
1259+
1260+
const expectedMessage =
1261+
'Flutter failed to run "foo --bar". The filename or extension is too long.\n'
1262+
'ProcessException: The filename or extension is too long\n'
1263+
' Command: foo --bar\n'
1264+
'Please consider moving the Flutter SDK and/or project to a shorter path, '
1265+
'or enabling long paths on Windows.';
1266+
await expectLater(
1267+
() => processManager.start(<String>['foo', '--bar']),
1268+
throwsToolExit(message: expectedMessage),
1269+
);
1270+
await expectLater(
1271+
() => processManager.run(<String>['foo', '--bar']),
1272+
throwsToolExit(message: expectedMessage),
1273+
);
1274+
expect(
1275+
() => processManager.runSync(<String>['foo', '--bar']),
1276+
throwsToolExit(message: expectedMessage),
1277+
);
1278+
});
1279+
11871280
for (final (name, errorCode) in const <(String, int)>[
11881281
('Windows Application Control policy', kApplicationControlPolicyBlocked),
11891282
('Windows group policy', kAccessDisabledByPolicy),

0 commit comments

Comments
 (0)