Skip to content

Commit 8912fc9

Browse files
authored
[flutter_tools] Gracefully handle EROFS and write-protected file system errors (flutter#192431)
When `flutter assemble` or other Flutter tool commands attempt to create build directories or write files to a read-only file system (such as Xcode build sandboxes or read-only volume mounts), the tool previously threw an unhandled `FileSystemException` instead of exiting cleanly with an actionable message. This change: - Handles POSIX errno 30 (`EROFS`, Read-only file system) in `_handlePosixException` in `packages/flutter_tools/lib/src/base/error_handling_io.dart`. - Handles Windows `ERROR_WRITE_PROTECT` (19) and `ERROR_PRIVILEGE_NOT_HELD` (1314) in `_handleWindowsException`. - Translates these errors into clean `ToolExit` messages instructing users to verify read/write permissions for the project and SDK. - Adds comprehensive regression unit tests for Linux, macOS, and Windows in `packages/flutter_tools/test/general.shard/base/error_handling_io_test.dart`. Fixes [flutter#83053](flutter#83053) ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [flutter/website]: https://github.com/flutter/website [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 6f44b24 commit 8912fc9

2 files changed

Lines changed: 184 additions & 10 deletions

File tree

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

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,9 @@ class ErrorHandlingFileSystem extends ForwardingFileSystem {
9696
final T result = operation();
9797
if (result is Future) {
9898
return (result.whenComplete(() {
99-
ErrorHandlingFileSystem._noExitOnFailure = previousValue;
100-
})) as T;
99+
ErrorHandlingFileSystem._noExitOnFailure = previousValue;
100+
}))
101+
as T;
101102
}
102103
ErrorHandlingFileSystem._noExitOnFailure = previousValue;
103104
return result;
@@ -1367,8 +1368,9 @@ void _handlePosixException(
13671368
// https://github.com/apple/darwin-xnu/blob/main/bsd/dev/dtrace/scripts/errno.d
13681369
const eperm = 1;
13691370
const enoent = 2;
1370-
const enospc = 28;
13711371
const eacces = 13;
1372+
const enospc = 28;
1373+
const erofs = 30;
13721374
// Catch errors and bail when:
13731375
final String? errorMessage = switch (errorCode) {
13741376
enoent =>
@@ -1380,6 +1382,17 @@ void _handlePosixException(
13801382
'$message. The target device is full.'
13811383
'\n$e\n'
13821384
'Free up space and try again.',
1385+
erofs => () {
1386+
final errorBuffer = StringBuffer();
1387+
if (message != null && message.isNotEmpty) {
1388+
errorBuffer.writeln('$message.');
1389+
}
1390+
errorBuffer.writeln(
1391+
'The file system is read-only. Please ensure that the SDK and/or project '
1392+
'is installed in a location with write permissions.',
1393+
);
1394+
return errorBuffer.toString().trim();
1395+
}(),
13831396
eperm || eacces => () {
13841397
final errorBuffer = StringBuffer();
13851398
if (message != null && message.isNotEmpty) {
@@ -1443,16 +1456,18 @@ void _handleWindowsException(Exception e, String? message, int errorCode) {
14431456
// https://docs.microsoft.com/en-us/windows/win32/debug/system-error-codes
14441457
const kFileNotFound = 2;
14451458
const kPathNotFound = 3;
1446-
const kDeviceFull = 112;
1459+
const kAccessDenied = 5;
1460+
const kWriteProtect = 19;
14471461
const kSharingViolation = 32;
14481462
const kLockViolation = 33;
1449-
const kUserMappedSectionOpened = 1224;
1450-
const kAccessDenied = 5;
1451-
const kFatalDeviceHardwareError = 483;
1463+
const kDeviceFull = 112;
14521464
const kDeviceDoesNotExist = 433;
1453-
const kApplicationControlPolicyBlocked = 4551;
1454-
const kAccessDisabledByPolicy = 1260;
14551465
const kSystemIntegrityPolicyViolation = 454;
1466+
const kFatalDeviceHardwareError = 483;
1467+
const kUserMappedSectionOpened = 1224;
1468+
const kAccessDisabledByPolicy = 1260;
1469+
const kPrivilegeNotHeld = 1314;
1470+
const kApplicationControlPolicyBlocked = 4551;
14561471

14571472
// Catch errors and bail when:
14581473
final String? errorMessage = switch (errorCode) {
@@ -1461,7 +1476,7 @@ void _handleWindowsException(Exception e, String? message, int errorCode) {
14611476
'\n$e\n'
14621477
'This can sometimes happen if the file was deleted or moved while the tool was running.'
14631478
' Try running "flutter clean" and try again.',
1464-
kAccessDenied =>
1479+
kAccessDenied || kWriteProtect || kPrivilegeNotHeld =>
14651480
'$message. The flutter tool cannot access the file or directory.\n'
14661481
'Please ensure that the SDK and/or project is installed in a location '
14671482
'that has read/write permissions for the current user.',

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

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,8 @@ void main() {
157157
const kDeviceFull = 112;
158158
const kUserMappedSectionOpened = 1224;
159159
const kUserPermissionDenied = 5;
160+
const kWriteProtect = 19;
161+
const kPrivilegeNotHeld = 1314;
160162
const kFatalDeviceHardwareError = 483;
161163
const kDeviceDoesNotExist = 433;
162164

@@ -228,6 +230,29 @@ void main() {
228230
expect(() => file.createSync(), throwsToolExit(message: expectedMessage));
229231
});
230232

233+
testWithoutContext('when write protected or privilege not held', () async {
234+
final fileSystem = ErrorHandlingFileSystem(
235+
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
236+
platform: windowsPlatform,
237+
);
238+
final File file = fileSystem.file('file');
239+
240+
exceptionHandler.addError(
241+
file,
242+
FileSystemOp.write,
243+
FileSystemException('', file.path, const OSError('', kWriteProtect)),
244+
);
245+
exceptionHandler.addError(
246+
file,
247+
FileSystemOp.create,
248+
FileSystemException('', file.path, const OSError('', kPrivilegeNotHeld)),
249+
);
250+
251+
const expectedMessage = 'The flutter tool cannot access the file';
252+
expect(() async => file.writeAsString(''), throwsToolExit(message: expectedMessage));
253+
expect(() => file.createSync(), throwsToolExit(message: expectedMessage));
254+
});
255+
231256
testWithoutContext('when writing to a full device', () async {
232257
final fileSystem = ErrorHandlingFileSystem(
233258
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
@@ -420,13 +445,80 @@ void main() {
420445
const eperm = 1;
421446
const enospc = 28;
422447
const eacces = 13;
448+
const erofs = 30;
423449

424450
late FileExceptionHandler exceptionHandler;
425451

426452
setUp(() {
427453
exceptionHandler = FileExceptionHandler();
428454
});
429455

456+
testWithoutContext('when on a read-only file system (erofs)', () async {
457+
final fileSystem = ErrorHandlingFileSystem(
458+
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
459+
platform: linuxPlatform,
460+
);
461+
final Directory directory = fileSystem.directory('dir')..createSync();
462+
final File file = directory.childFile('file');
463+
464+
exceptionHandler.addError(
465+
file,
466+
FileSystemOp.create,
467+
FileSystemException('', file.path, const OSError('', erofs)),
468+
);
469+
exceptionHandler.addError(
470+
file,
471+
FileSystemOp.write,
472+
FileSystemException('', file.path, const OSError('', erofs)),
473+
);
474+
exceptionHandler.addError(
475+
file,
476+
FileSystemOp.delete,
477+
FileSystemException('', file.path, const OSError('', erofs)),
478+
);
479+
480+
const writeMessage =
481+
'Flutter failed to write to a file at "dir/file".\n'
482+
'The file system is read-only. Please ensure that the SDK and/or project '
483+
'is installed in a location with write permissions.';
484+
expect(() async => file.writeAsBytes(<int>[0]), throwsToolExit(message: writeMessage));
485+
expect(() async => file.writeAsString(''), throwsToolExit(message: writeMessage));
486+
expect(() => file.writeAsBytesSync(<int>[0]), throwsToolExit(message: writeMessage));
487+
expect(() => file.writeAsStringSync(''), throwsToolExit(message: writeMessage));
488+
489+
const createMessage =
490+
'Flutter failed to create file at "dir/file".\n'
491+
'The file system is read-only. Please ensure that the SDK and/or project '
492+
'is installed in a location with write permissions.';
493+
expect(() => file.createSync(), throwsToolExit(message: createMessage));
494+
expect(() async => file.createSync(recursive: true), throwsToolExit(message: createMessage));
495+
496+
final Directory parent = fileSystem.directory('parent')..createSync();
497+
final Directory childDir = parent.childDirectory('childDir');
498+
499+
exceptionHandler.addError(
500+
childDir,
501+
FileSystemOp.create,
502+
FileSystemException('', childDir.path, const OSError('', erofs)),
503+
);
504+
exceptionHandler.addError(
505+
childDir,
506+
FileSystemOp.delete,
507+
FileSystemException('', childDir.path, const OSError('', erofs)),
508+
);
509+
510+
const dirCreateMessage =
511+
'Flutter failed to create a directory at "parent/childDir".\n'
512+
'The file system is read-only. Please ensure that the SDK and/or project '
513+
'is installed in a location with write permissions.';
514+
expect(() async => childDir.create(), throwsToolExit(message: dirCreateMessage));
515+
expect(() => childDir.createSync(), throwsToolExit(message: dirCreateMessage));
516+
expect(
517+
() async => childDir.createSync(recursive: true),
518+
throwsToolExit(message: dirCreateMessage),
519+
);
520+
});
521+
430522
testWithoutContext('when access is denied', () async {
431523
final fileSystem = ErrorHandlingFileSystem(
432524
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
@@ -643,12 +735,79 @@ void main() {
643735
const eperm = 1;
644736
const enospc = 28;
645737
const eacces = 13;
738+
const erofs = 30;
646739
late FileExceptionHandler exceptionHandler;
647740

648741
setUp(() {
649742
exceptionHandler = FileExceptionHandler();
650743
});
651744

745+
testWithoutContext('when on a read-only file system (erofs)', () async {
746+
final fileSystem = ErrorHandlingFileSystem(
747+
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),
748+
platform: macOSPlatform,
749+
);
750+
final Directory directory = fileSystem.directory('dir')..createSync();
751+
final File file = directory.childFile('file');
752+
753+
exceptionHandler.addError(
754+
file,
755+
FileSystemOp.create,
756+
FileSystemException('', file.path, const OSError('', erofs)),
757+
);
758+
exceptionHandler.addError(
759+
file,
760+
FileSystemOp.write,
761+
FileSystemException('', file.path, const OSError('', erofs)),
762+
);
763+
exceptionHandler.addError(
764+
file,
765+
FileSystemOp.delete,
766+
FileSystemException('', file.path, const OSError('', erofs)),
767+
);
768+
769+
const writeMessage =
770+
'Flutter failed to write to a file at "dir/file".\n'
771+
'The file system is read-only. Please ensure that the SDK and/or project '
772+
'is installed in a location with write permissions.';
773+
expect(() async => file.writeAsBytes(<int>[0]), throwsToolExit(message: writeMessage));
774+
expect(() async => file.writeAsString(''), throwsToolExit(message: writeMessage));
775+
expect(() => file.writeAsBytesSync(<int>[0]), throwsToolExit(message: writeMessage));
776+
expect(() => file.writeAsStringSync(''), throwsToolExit(message: writeMessage));
777+
778+
const createMessage =
779+
'Flutter failed to create file at "dir/file".\n'
780+
'The file system is read-only. Please ensure that the SDK and/or project '
781+
'is installed in a location with write permissions.';
782+
expect(() => file.createSync(), throwsToolExit(message: createMessage));
783+
expect(() async => file.createSync(recursive: true), throwsToolExit(message: createMessage));
784+
785+
final Directory parent = fileSystem.directory('parent')..createSync();
786+
final Directory childDir = parent.childDirectory('childDir');
787+
788+
exceptionHandler.addError(
789+
childDir,
790+
FileSystemOp.create,
791+
FileSystemException('', childDir.path, const OSError('', erofs)),
792+
);
793+
exceptionHandler.addError(
794+
childDir,
795+
FileSystemOp.delete,
796+
FileSystemException('', childDir.path, const OSError('', erofs)),
797+
);
798+
799+
const dirCreateMessage =
800+
'Flutter failed to create a directory at "parent/childDir".\n'
801+
'The file system is read-only. Please ensure that the SDK and/or project '
802+
'is installed in a location with write permissions.';
803+
expect(() async => childDir.create(), throwsToolExit(message: dirCreateMessage));
804+
expect(() => childDir.createSync(), throwsToolExit(message: dirCreateMessage));
805+
expect(
806+
() async => childDir.createSync(recursive: true),
807+
throwsToolExit(message: dirCreateMessage),
808+
);
809+
});
810+
652811
testWithoutContext('when access is denied', () async {
653812
final fileSystem = ErrorHandlingFileSystem(
654813
delegate: MemoryFileSystem.test(opHandle: exceptionHandler.opHandle),

0 commit comments

Comments
 (0)