Skip to content

[local_auth] Adopt structured errors, and remove useErrorDialogs #9981

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
auto-submit merged 30 commits into from
Oct 16, 2025
Merged

[local_auth] Adopt structured errors, and remove useErrorDialogs #9981

auto-submit merged 30 commits into from
Oct 16, 2025
+124 −198

Conversation

@stuartmorgan-g
Copy link
Collaborator

@stuartmorgan-g stuartmorgan-g commented Sep 9, 2025

Switches from PlatformExceptions to new LocalAuthExceptions, which contain structured error information (specifically, a code that is a documented enum, rather than a list of magic strings that are used inconsistently and not all documented), bringing the plugin into alignment with [our current best practices](https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#platform-exception-handling. In addition to being clearer and easier to use for clients, this adds significantly more granular error codes than we currently have, which allows clients to better handle specific cases.

Since this must be done as a breaking change (since the current PlatformExceptions are a combination of documented and de-facto API), this batches another breaking change, which is removing the error dialogs from the plugin, for the reasons described in flutter/flutter#175125.

Since this is adding far more specific error codes, the PR also makes the internal change of passing essentially all native failure cases across the language boundary and then doing mapping to the cross-platform codes in Dart code, in keeping with our general recent practice of moving logic to the Dart side when there's no need for it to be native.

Fixes flutter/flutter#113687
Fixes flutter/flutter#175125
Fixes flutter/flutter#151513
Fixes flutter/flutter#132757
Fixes flutter/flutter#148947
Fixes flutter/flutter#173506
Fixes flutter/flutter#174191
Closes flutter/flutter#96646
Fixes flutter/flutter#117810
Closes flutter/flutter#141283
Closes flutter/flutter#173142

Pre-Review Checklist

Footnotes

  1. Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩2 ↩3

@stuartmorgan-g
Copy link
Collaborator Author

stuartmorgan-g commented Sep 9, 2025

@tarrinneal Please review everything other than the Android and iOS changes.

@stuartmorgan-g stuartmorgan-g added triage-ios Should be looked at in iOS triage triage-android Should be looked at in Android triage labels Sep 9, 2025
gemini-code-assist[bot]
gemini-code-assist bot reviewed Sep 9, 2025
View reviewed changes
Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request is a significant and well-executed refactoring of the local_auth plugin. It successfully replaces PlatformException with a more robust, structured LocalAuthException, and removes the useErrorDialogs option, giving developers more control over the user experience. The changes are consistently applied across all supported platforms, and the public API of the local_auth package is cleaner as a result. My review includes a few minor suggestions to improve the example applications to better demonstrate handling of the new exception type.

@stuartmorgan-g stuartmorgan-g mentioned this pull request Sep 9, 2025
Closed
stuartmorgan-g and others added 3 commits September 11, 2025 10:53
tarrinneal
tarrinneal approved these changes Sep 16, 2025
View reviewed changes
Copy link
Contributor

@tarrinneal tarrinneal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Flagged a few typos, but the (non-ios, non-android) code all looks solid to me.

packages/local_auth/local_auth/example/lib/main.dart
Comment on lines +95 to 106
print(e);
setState(() {
_isAuthenticating = false;
if (e.code != LocalAuthExceptionCode.userCanceled &&
e.code != LocalAuthExceptionCode.systemCanceled) {
_authorized =
'Error - ${e.code.name}${e.description != null ? ': ${e.description}' : ''}';
}
});
return;
} on PlatformException catch (e) {
print(e);
Copy link
Contributor

@tarrinneal tarrinneal Sep 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is having print statements in catch blocks normal for our examples?

Copy link
Collaborator Author

@stuartmorgan-g stuartmorgan-g Sep 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not uncommon; our examples have historically been pretty bare-bones, and tend to skew more toward enabling manual testing than showing best practices. Some stick the errors into some in-app UI, which is an improvement, but also more code in the example.

It's something that ideally we should address, but polishing example apps that most clients will probably never actually run is also pretty low priority, so I've never followed up on it.

vashworth
vashworth approved these changes Sep 16, 2025
View reviewed changes
Copy link
Contributor

@vashworth vashworth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

iOS side LGTM

@stuartmorgan-g
Copy link
Collaborator Author

stuartmorgan-g commented Sep 17, 2025

Aside, my brain does not like 'canceled' with one 'l' no matter how many times Google tells me that's how we do it here in America.

If I hadn't been interacting with the Android error codes there's no way I would have actually remembered to do it that way (per Flutter style).

@stuartmorgan-g stuartmorgan-g mentioned this pull request Sep 17, 2025
Merged
11 tasks
auto-submit bot pushed a commit that referenced this pull request Sep 30, 2025
@stuartmorgan-g
[local_auth] Adopt structured errors - platform interface (#10023)
321a584 
Platform interface portion of #9981

- Adds the new `LocalAuthException` class for structured errors.
- Deprecates `AuthenticationOptions.useErrorDialogs`

Part of:
- flutter/flutter#113687
- flutter/flutter#175125

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
@stuartmorgan-g stuartmorgan-g mentioned this pull request Sep 30, 2025
Merged
11 tasks
@stuartmorgan-g stuartmorgan-g added the federated: all_changes PR that contains changes for all packages for a federated plugin change label Sep 30, 2025
auto-submit bot pushed a commit that referenced this pull request Oct 16, 2025
@stuartmorgan-g
[local_auth] Adopt structured errors and remove useErrorDialogs - pla…
835dccb 
…tform implementations (#10147)

Platform implementation portion of #9981

- Adds the new `LocalAuthException` class for structured errors.
- Deprecates `AuthenticationOptions.useErrorDialogs`

Part of:
- flutter/flutter#113687
- flutter/flutter#175125

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
@stuartmorgan-g stuartmorgan-g added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 16, 2025
@auto-submit auto-submit bot merged commit 61b3c54 into flutter:main Oct 16, 2025
80 checks passed
engine-flutter-autoroll added a commit to engine-flutter-autoroll/flutter that referenced this pull request Oct 17, 2025
@engine-flutter-autoroll
61b3c54 [local_auth] Adopt structured errors, and remove `useErrorDia…
a3fcae8 
…logs` (flutter/packages#9981)
@engine-flutter-autoroll engine-flutter-autoroll mentioned this pull request Oct 17, 2025
Merged
github-merge-queue bot pushed a commit to flutter/flutter that referenced this pull request Oct 17, 2025
@engine-flutter-autoroll
Roll Packages from 835dccb to 3747006 (3 revisions) (#177170)
e5c22aa 
flutter/packages@835dccb...3747006

2025-10-16 [email protected] Manual roll Flutter from
7cd821c to a873a27 (22 revisions) (flutter/packages#10244)
2025-10-16 [email protected] [local_auth] Adopt structured errors,
and remove `useErrorDialogs` (flutter/packages#9981)
2025-10-16 [email protected] [video_player] Move most Android
event logic to Dart (flutter/packages#10128)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages-flutter-autoroll
Please CC [email protected] on the revert to ensure that a
human
is aware of the problem.

To file a bug in Flutter:
https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
reidbaker pushed a commit to AbdeMohlbi/flutter that referenced this pull request Dec 10, 2025
@engine-flutter-autoroll @reidbaker
Roll Packages from 835dccb to 3747006 (3 revisions) (flutter#177170)
94500f2 
flutter/packages@835dccb...3747006

2025-10-16 [email protected] Manual roll Flutter from
7cd821c to a873a27 (22 revisions) (flutter/packages#10244)
2025-10-16 [email protected] [local_auth] Adopt structured errors,
and remove `useErrorDialogs` (flutter/packages#9981)
2025-10-16 [email protected] [video_player] Move most Android
event logic to Dart (flutter/packages#10128)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages-flutter-autoroll
Please CC [email protected] on the revert to ensure that a
human
is aware of the problem.

To file a bug in Flutter:
https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mboetger mboetger mboetger approved these changes

@vashworth vashworth vashworth approved these changes

@tarrinneal tarrinneal tarrinneal approved these changes

@okorohelijah okorohelijah Awaiting requested review from okorohelijah

+1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

autosubmit Merge PR when tree becomes green via auto submit App federated: all_changes PR that contains changes for all packages for a federated plugin change p: local_auth triage-android Should be looked at in Android triage triage-ios Should be looked at in iOS triage

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

iOS plugin does not show "go to settings" dialog when biometrics was switched off in settings [local_auth_android] UI for password authentication shows text for biometric authentication [local_auth][iOS] useErrorDialogs= false still shows system dialog when locked out by system [local_auth] Improve exception handling of local_auth plugin [local_auth] "authenticate" with parameter "useErrorDialogs = true" does not open a dialog
[local_auth] Document how to eliminate the fallback button in biometrics dialog on iOS via localizedFallbackTitle [local_auth] Suggestion for changes in error handling for LocalAuthentication().authenticate() Unnecessary biometryLockout UI handling in LocalAuthPlugin.swift [local_auth] on Windows, with only password enabled, authenticate returns NoHardware Android - LocalAuth Plugin getEnrolledBiometrics throws when no Activity is available

4 participants

@stuartmorgan-g @mboetger @vashworth @tarrinneal