Skip to content

Commit e5792f6

Browse files
[beta] [flutter_tools] Exit cleanly when Windows path exceeds MAX_PATH (OS Error 206) (#195072)
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. ### 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 6630731 commit e5792f6

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
@@ -1455,6 +1455,7 @@ void _handleWindowsException(Exception e, String? message, int errorCode) {
14551455
const kSharingViolation = 32;
14561456
const kLockViolation = 33;
14571457
const kDeviceFull = 112;
1458+
const kFilenameExcedRange = 206;
14581459
const kDeviceDoesNotExist = 433;
14591460
const kSystemIntegrityPolicyViolation = 454;
14601461
const kFatalDeviceHardwareError = 483;
@@ -1478,6 +1479,11 @@ void _handleWindowsException(Exception e, String? message, int errorCode) {
14781479
'$message. The target device is full.'
14791480
'\n$e\n'
14801481
'Free up space and try again.',
1482+
kFilenameExcedRange =>
1483+
'${message != null ? "$message. " : ""}The filename or extension is too long.\n'
1484+
'$e\n'
1485+
'Please consider moving the Flutter SDK and/or project to a shorter path, '
1486+
'or enabling long paths on Windows.',
14811487
kSharingViolation || kLockViolation || kUserMappedSectionOpened =>
14821488
'$message. The file is being used by another program.'
14831489
'\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 kWriteProtect = 19;
@@ -439,6 +440,41 @@ void main() {
439440
throwsToolExit(message: 'The flutter tool cannot access the file or directory'),
440441
);
441442
});
443+
444+
testWithoutContext('when the filename or extension is too long', () async {
445+
final fileSystem = ErrorHandlingFileSystem(
446+
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
447+
platform: windowsPlatform,
448+
);
449+
final File file = fileSystem.file('file');
450+
451+
exceptionHandler.addError(
452+
file,
453+
FileSystemOp.write,
454+
FileSystemException('', file.path, const OSError('', kFilenameExcedRange)),
455+
);
456+
exceptionHandler.addError(
457+
file,
458+
FileSystemOp.open,
459+
FileSystemException('', file.path, const OSError('', kFilenameExcedRange)),
460+
);
461+
exceptionHandler.addError(
462+
file,
463+
FileSystemOp.create,
464+
FileSystemException('', file.path, const OSError('', kFilenameExcedRange)),
465+
);
466+
467+
const expectedMessage = 'The filename or extension is too long.';
468+
await expectLater(
469+
() => file.writeAsBytes(<int>[0]),
470+
throwsToolExit(message: expectedMessage),
471+
);
472+
await expectLater(() => file.writeAsString(''), throwsToolExit(message: expectedMessage));
473+
expect(() => file.writeAsBytesSync(<int>[0]), throwsToolExit(message: expectedMessage));
474+
expect(() => file.writeAsStringSync(''), throwsToolExit(message: expectedMessage));
475+
expect(() => file.openSync(), throwsToolExit(message: expectedMessage));
476+
expect(() => file.createSync(), throwsToolExit(message: expectedMessage));
477+
});
442478
});
443479

444480
group('throws ToolExit on Linux', () {
@@ -1140,6 +1176,7 @@ Please ensure that the SDK and/or project is installed in a location that has re
11401176

11411177
group('ProcessManager on windows throws tool exit', () {
11421178
const kDeviceFull = 112;
1179+
const kFilenameExcedRange = 206;
11431180
const kUserMappedSectionOpened = 1224;
11441181
const kUserPermissionDenied = 5;
11451182
const kApplicationControlPolicyBlocked = 4551;
@@ -1340,6 +1377,62 @@ Please ensure that the SDK and/or project is installed in a location that has re
13401377
);
13411378
});
13421379

1380+
testWithoutContext('when the filename or extension is too long', () async {
1381+
final fakeProcessManager = FakeProcessManager.list(<FakeCommand>[
1382+
const FakeCommand(
1383+
command: <String>['foo', '--bar'],
1384+
exception: ProcessException(
1385+
'foo',
1386+
<String>['--bar'],
1387+
'The filename or extension is too long',
1388+
kFilenameExcedRange,
1389+
),
1390+
),
1391+
const FakeCommand(
1392+
command: <String>['foo', '--bar'],
1393+
exception: ProcessException(
1394+
'foo',
1395+
<String>['--bar'],
1396+
'The filename or extension is too long',
1397+
kFilenameExcedRange,
1398+
),
1399+
),
1400+
const FakeCommand(
1401+
command: <String>['foo', '--bar'],
1402+
exception: ProcessException(
1403+
'foo',
1404+
<String>['--bar'],
1405+
'The filename or extension is too long',
1406+
kFilenameExcedRange,
1407+
),
1408+
),
1409+
]);
1410+
1411+
final ProcessManager processManager = createProcessManager(
1412+
delegate: fakeProcessManager,
1413+
platform: windowsPlatform,
1414+
);
1415+
1416+
const expectedMessage =
1417+
'Flutter failed to run "foo --bar". The filename or extension is too long.\n'
1418+
'ProcessException: The filename or extension is too long\n'
1419+
' Command: foo --bar\n'
1420+
'Please consider moving the Flutter SDK and/or project to a shorter path, '
1421+
'or enabling long paths on Windows.';
1422+
await expectLater(
1423+
() => processManager.start(<String>['foo', '--bar']),
1424+
throwsToolExit(message: expectedMessage),
1425+
);
1426+
await expectLater(
1427+
() => processManager.run(<String>['foo', '--bar']),
1428+
throwsToolExit(message: expectedMessage),
1429+
);
1430+
expect(
1431+
() => processManager.runSync(<String>['foo', '--bar']),
1432+
throwsToolExit(message: expectedMessage),
1433+
);
1434+
});
1435+
13431436
for (final (name, errorCode) in const <(String, int)>[
13441437
('Windows Application Control policy', kApplicationControlPolicyBlocked),
13451438
('Windows group policy', kAccessDisabledByPolicy),

0 commit comments

Comments
 (0)