Repository navigation
Description
Problem
For most failures, an app can tell them apart only by PlatformException.code: for example, to show its own message, translated into the user's language, or to handle one case specially. But the codes aren't documented, and they aren't treated as stable, so apps can't rely on them:
- They change in ordinary fixes. fix(android): update error code to explorer_not_found when file explorer is missing (#1850) #2008 changed Android's code for a missing file explorer from
invalid_format_typetoexplorer_not_found. That was a reasonable fix, but an app that matched the earlier code silently stops matching. - They disappear.
read_external_storage_deniedstopped appearing in 8.1.5, when the plugin stopped requesting that permission. (Our app's handling for it went dead without anyone noticing, until we found it while upgrading.) - The same situation gets different codes on different platforms. Starting a pick while another is open is rejected with
multiple_requeston iOS, butalready_activeon Android. - The naming varies:
invalid_arguments,ENTITLEMENT_NOT_FOUND,"Unsupported file extension","Error while saving file".
And some failures produce no error at all. On Android, when the user picks several files and none of them can be read, the result is an empty list, as if the user had cancelled. (A single picked file that can't be read usually fails with unknown_path instead.) iOS had the same problem until file_picker_darwin 2.3.1 fixed #2248, by adding one more code, load_failed.
The codes in 13.1.0, for reference:
- file_picker_darwin 2.3.1:
multiple_request,invalid_arguments,load_failed,"Unsupported file extension",save_file_error,ENTITLEMENT_CHECK_FAILED,ENTITLEMENT_NOT_FOUND,ENTITLEMENT_REQUIRED_WRITE - android_file_picker 2.1.0:
already_active,explorer_not_found,unknown_activity,unknown_path,file_picker_error,out_of_memory,no_activity,"Error while saving file"
(I haven't checked web, Linux or Windows.)
Proposal
Since 14.0.0 is already a breaking release (#2224), it could be a good time to adopt the model Flutter's own local_auth plugin moved to in its 3.0.0 release:
- A typed exception in the platform interface. For example,
FilePickerException implements Exception, with aFilePickerErrorCodeenum (alreadyActive,explorerNotFound,invalidArguments, …,unknown). local_auth's 3.0.0 changelog says it "ThrowsLocalAuthExceptions rather thanPlatformExceptions for most failures cases, allowing structured error handling using the specificLocalAuthExceptionCodevalues"; google_sign_in 7.x does the same withGoogleSignInExceptionandGoogleSignInExceptionCode. file_picker's ownIllegalCharacterInFileNameException(exported in ExportIllegalCharacterInFileNameExceptionFixes #2076 #2077) is already a typed exception of this kind. - The same code for the same situation on every platform, and documented, so apps can rely on them. New codes could still be added in minor releases, if the docs ask apps to keep a default case.
- The mapping in one place per platform. In local_auth_android, the native side reports an outcome as a typed result,
AuthResultwith anAuthResultCodeenum (via Pigeon), and the Dart side turns it into aLocalAuthExceptionin a singleswitchover that enum. Because theswitchmust cover every enum value, a new native result code doesn't compile until someone maps it. With file_picker's currentMethodChannel, the closest equivalent is one helper that every channel call goes through, mapping the native code strings toFilePickerErrorCode, withunknownas the default. That keeps the mapping in one place, though the compiler can't check it against the native side. (Moving to Pigeon would allow the compiler-checked version; that's a bigger change, suggested in Use Pigeon for the platform channels, so the Dart and native sides are checked against each other #2258.) - Expected failures that currently produce no error should throw one, as file_picker_darwin 2.3.1 now does for iOS: when none of the picked items can be loaded, pickFiles returns an empty list, as if the user cancelled #2248. The Android multiple-file case above is another.
Activity
vicajilau commentedon Oct 15, 2026
A quick update on one part of this: picking several files on Android when none of them can be read now fails with
unknown_path, like a single pick, instead of returning an empty list (android_file_picker 2.1.1, #2263).vicajilau commentedon Oct 15, 2026
@navaronbracke here's a proposal to do this without waiting for 14.0.0, so it can ship in a 13.x minor.
Shape. In
file_picker_platform_interface:Extending
PlatformExceptionkeeps this non breaking.on PlatformException catch (e)ande.codekeep working with today's strings, and apps can move toon FilePickerException catch (e)and switch overe.errorCode.Mapping. One helper in the platform interface that every method channel call in android_file_picker and file_picker_darwin goes through, turning the native code into a
FilePickerErrorCode:FilePickerErrorCodealreadyActivealready_activemultiple_requestloadFailedunknown_pathload_failedinvalidArgumentsinvalid_argumentsunsupportedExtensionUnsupported file extensionnoPickerAvailableexplorer_not_foundsaveFailedError while saving filesave_file_erroroutOfMemoryout_of_memorymissingEntitlementENTITLEMENT_NOT_FOUND,ENTITLEMENT_REQUIRED_WRITE,ENTITLEMENT_CHECK_FAILEDunknownfile_picker_error,unknown_activity,no_activity)The native strings stay as they are, so nothing changes for existing apps. The codes get documented in the README, and new values can be added in minor releases, since the docs ask apps to keep a default case. 14.0.0 can then unify the native strings themselves.
Scope. One PR with the exception, the helper with its tests, the Android and Darwin mapping, and the README table. Web, Linux and Windows report their errors from Dart (
ArgumentError,UnsupportedError,WindowsException), so they stay out of this first step.compose_box [nfc]: Drop dead code handling a file_picker permission e…
deps: Upgrade file_picker to 13.1.0, with the packages that requires
compose_box: Show a translated message when no picked file could be l…
compose_box [nfc]: Drop dead code handling a file_picker permission e…
deps: Upgrade file_picker to 13.1.0, with the packages that requires
compose_box: Show a translated message when no picked file could be l…
compose_box [nfc]: Drop dead code handling a file_picker permission e…
deps: Upgrade file_picker to 13.1.0, with the packages that requires
compose_box: Show a translated message when no picked file could be l…
vicajilau commentedon Oct 26, 2026
@navaronbracke following up from #2287, here's the 14.0.0 version of this, now that a breaking change is on the table.
Shape. In
file_picker_platform_interface:Runtime failures throw a
FilePickerExceptioninstead of a rawPlatformException. Programming errors, like an invalid extension filter, stayArgumentError, as Dart APIs usually do.detailskeeps what the native side sends, such as the per item reasons ofload_failedfrom #2274.Mapping. One helper in the platform interface turns a
PlatformExceptioninto aFilePickerException, and every method channel call in android_file_picker and file_picker_darwin goes through it:FilePickerErrorCodealreadyActivealready_activemultiple_requestloadFailedunknown_pathload_failed,unknown_pathinvalidArgumentsinvalid_argumentsunsupportedExtensionUnsupported file extensionnoPickerAvailableexplorer_not_foundwindowNotFoundwindow_not_foundsaveFailedError while saving filesave_file_erroroutOfMemoryout_of_memorymissingEntitlementENTITLEMENT_NOT_FOUND,ENTITLEMENT_REQUIRED_WRITE,ENTITLEMENT_CHECK_FAILEDunknownThe codes get documented in the README, new values can be added in minor releases since the docs ask apps to keep a default case, and the migration guide shows the
on PlatformExceptiontoon FilePickerExceptionchange.Scope. One PR on the 14.0.0 branch with the exception, the helper and its tests, the Android and Darwin mapping, the README table and the migration step. Web, Linux and Windows don't report runtime failures over a method channel today, so they only need to keep throwing
ArgumentErrorfor bad input.vicajilau commentedon Nov 1, 2026
A few updates to the mapping above, from the v14 work since:
unknown_result, when an activity ends with an unexpected result code or a save comes back without a location, andinvalid_type. Both look likeloadFailedfor a pick andsaveFailedfor a save.file_picker_errorfrom the catch all inprocessFiles(), andunknown_activity. They are missing from the table, andloadFailedfits both.portal_errorwhen the file chooser portal fails, so Linux does report runtime failures now. It would map toloadFailed, or tosaveFailedforsaveFile(), so the Scope paragraph needs Linux too.WindowsExceptionfrom the dialog calls, not aPlatformException. IfFilePickerExceptionis meant to be the one type apps catch, Windows needs the same mapping. I'd add it to the scope too.And now that
saveFailedhas a mapping, the Android side should send a real code for it instead of the messageError while saving file, which is easy to do in the same PR.vicajilau commentedon Nov 14, 2026
@navaronbracke this is the last open API decision for 14.0.0, so I would like your view before building it. The 14.0.0 version above makes runtime failures throw a
FilePickerExceptionwith aFilePickerErrorCode, instead of a rawPlatformException, on every platform including Linux and Windows. Does that shape work for you, or would you rather leave this out of 14.0.0 and keepPlatformException? Either is fine with me, I just do not want it to be the thing that holds the release back.