Skip to content

Typed, documented error codes, like local_auth's LocalAuthException #2262

Open

Description

@chrisbobbe

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_type to explorer_not_found. That was a reasonable fix, but an app that matched the earlier code silently stops matching.
  • They disappear. read_external_storage_denied stopped 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_request on iOS, but already_active on 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:

  1. A typed exception in the platform interface. For example, FilePickerException implements Exception, with a FilePickerErrorCode enum (alreadyActive, explorerNotFound, invalidArguments, …, unknown). local_auth's 3.0.0 changelog says it "Throws LocalAuthExceptions rather than PlatformExceptions for most failures cases, allowing structured error handling using the specific LocalAuthExceptionCode values"; google_sign_in 7.x does the same with GoogleSignInException and GoogleSignInExceptionCode. file_picker's own IllegalCharacterInFileNameException (exported in Export IllegalCharacterInFileNameException Fixes #2076 #2077) is already a typed exception of this kind.
  2. 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.
  3. The mapping in one place per platform. In local_auth_android, the native side reports an outcome as a typed result, AuthResult with an AuthResultCode enum (via Pigeon), and the Dart side turns it into a LocalAuthException in a single switch over that enum. Because the switch must cover every enum value, a new native result code doesn't compile until someone maps it. With file_picker's current MethodChannel, the closest equivalent is one helper that every channel call goes through, mapping the native code strings to FilePickerErrorCode, with unknown as 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.)
  4. 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

  1. vicajilau commented on Oct 15, 2026

    @vicajilau
    Owner

    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).

  2. vicajilau commented on Oct 15, 2026

    @vicajilau
    Owner

    @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:

    enum FilePickerErrorCode {
      alreadyActive,
      loadFailed,
      invalidArguments,
      unsupportedExtension,
      noPickerAvailable,
      saveFailed,
      outOfMemory,
      missingEntitlement,
      unknown,
    }
    
    class FilePickerException extends PlatformException {
      FilePickerException({
        required this.errorCode,
        required super.code,
        super.message,
        super.details,
      });
    
      final FilePickerErrorCode errorCode;
    }

    Extending PlatformException keeps this non breaking. on PlatformException catch (e) and e.code keep working with today's strings, and apps can move to on FilePickerException catch (e) and switch over e.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:

    FilePickerErrorCode Android iOS / macOS
    alreadyActive already_active multiple_request
    loadFailed unknown_path load_failed
    invalidArguments invalid_arguments
    unsupportedExtension Unsupported file extension
    noPickerAvailable explorer_not_found
    saveFailed Error while saving file save_file_error
    outOfMemory out_of_memory
    missingEntitlement ENTITLEMENT_NOT_FOUND, ENTITLEMENT_REQUIRED_WRITE, ENTITLEMENT_CHECK_FAILED
    unknown anything else (file_picker_error, unknown_activity, no_activity) anything else

    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.

  3. vicajilau commented on Oct 26, 2026

    @vicajilau
    Owner

    @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:

    enum FilePickerErrorCode {
      alreadyActive,
      loadFailed,
      invalidArguments,
      unsupportedExtension,
      noPickerAvailable,
      windowNotFound,
      saveFailed,
      outOfMemory,
      missingEntitlement,
      unknown,
    }
    
    final class FilePickerException implements Exception {
      const FilePickerException(this.code, {this.message, this.details});
    
      final FilePickerErrorCode code;
      final String? message;
      final Object? details;
    }

    Runtime failures throw a FilePickerException instead of a raw PlatformException. Programming errors, like an invalid extension filter, stay ArgumentError, as Dart APIs usually do. details keeps what the native side sends, such as the per item reasons of load_failed from #2274.

    Mapping. One helper in the platform interface turns a PlatformException into a FilePickerException, and every method channel call in android_file_picker and file_picker_darwin goes through it:

    FilePickerErrorCode Android iOS / macOS
    alreadyActive already_active multiple_request
    loadFailed unknown_path load_failed, unknown_path
    invalidArguments invalid_arguments
    unsupportedExtension Unsupported file extension
    noPickerAvailable explorer_not_found
    windowNotFound window_not_found
    saveFailed Error while saving file save_file_error
    outOfMemory out_of_memory
    missingEntitlement ENTITLEMENT_NOT_FOUND, ENTITLEMENT_REQUIRED_WRITE, ENTITLEMENT_CHECK_FAILED
    unknown anything else anything else

    The 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 PlatformException to on FilePickerException change.

    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 ArgumentError for bad input.

  4. vicajilau commented on Nov 1, 2026

    @vicajilau
    Owner

    A few updates to the mapping above, from the v14 work since:

    • Always answer Android picks and saves #2302 adds two Android codes for picks and saves that used to never complete: unknown_result, when an activity ends with an unexpected result code or a save comes back without a location, and invalid_type. Both look like loadFailed for a pick and saveFailed for a save.
    • Android also sends file_picker_error from the catch all in processFiles(), and unknown_activity. They are missing from the table, and loadFailed fits both.
    • Throw when the Linux file chooser portal fails #2301 makes Linux throw portal_error when the file chooser portal fails, so Linux does report runtime failures now. It would map to loadFailed, or to saveFailed for saveFile(), so the Scope paragraph needs Linux too.
    • Windows throws WindowsException from the dialog calls, not a PlatformException. If FilePickerException is meant to be the one type apps catch, Windows needs the same mapping. I'd add it to the scope too.

    And now that saveFailed has a mapping, the Android side should send a real code for it instead of the message Error while saving file, which is easy to do in the same PR.

  5. vicajilau commented on Nov 14, 2026

    @vicajilau
    Owner

    @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 FilePickerException with a FilePickerErrorCode, instead of a raw PlatformException, 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 keep PlatformException? Either is fine with me, I just do not want it to be the thing that holds the release back.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    suggestionNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions