Guides· October 6, 2026· 11 min read

Flutter Biometric Login in 2026: local_auth for Face ID and Fingerprint, Set Up and Debugged

Add Face ID and fingerprint login to a Flutter app with local_auth 3.0: Android and iOS setup, the new API, LocalAuthException codes and the fixes.

EN FlutterGo Engineering Engineering, FlutterGo 11 min read · October 6, 2026

Share this story

To add Face ID or fingerprint unlock to a Flutter app, you use local_auth, the Flutter team's plugin. In 2026 that means version 3.x, and most tutorials you'll find were written for 2.x. Version 3.0 renamed the option everyone copied (stickyAuth), deleted AuthenticationOptions, and swapped PlatformException for a typed LocalAuthException. Code from an older tutorial either won't compile or catches nothing.

This guide covers the current setup on Android and iOS, the 3.x API, every error code with what to do about it, and the one design mistake that makes a biometric lock look secure when it isn't. Versions and READMEs were checked on pub.dev and in the flutter/packages repository on October 6, 2026.

Which package should you use for biometrics in Flutter?

Use local_auth. It's published by flutter.dev, it's the plugin the official docs point to, and it's the only option with endorsed implementations for Android, iOS, macOS and Windows.

From pub.dev and the flutter/packages repository, October 6, 2026.

The platform packages are endorsed, so you only add local_auth to pubspec.yaml. Add local_auth_android or local_auth_darwin directly only if you import them, for example to customize dialog text.

dependencies:
  local_auth: ^3.0.2

If your app also stores a session token, add flutter_secure_storage (11.2.0 at the time of writing) as well. The last section explains why.

What changed in local_auth 3.0

If you're upgrading from 2.x, or following an older tutorial, these are the breaking changes from the 3.0.0 changelog:

The removal of useErrorDialogs is the one that changes behavior. In 2.x the plugin could show a native dialog telling the user to enroll a fingerprint. In 3.x nothing appears unless you build it, so a device with no enrolled biometrics just throws and the user sees whatever your catch block shows.

Android setup

The local_auth_android README lists three changes. Miss the first and authentication fails before any prompt appears.

1. Use FlutterFragmentActivity. The Android biometric prompt needs a FragmentActivity. Change MainActivity:

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
    // ...
}

If your AndroidManifest.xml points at FlutterActivity directly, change it there to FlutterFragmentActivity.

2. Add the permission to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC"/>

3. Use an AppCompat launch theme. The README says the LaunchTheme parent must be a Theme.AppCompat theme "to prevent crashes on Android 8 and below." In android/app/src/main/res/values/styles.xml:

<style name="LaunchTheme" parent="Theme.AppCompat.DayNight">
    ...
</style>

Since 3.x requires API 24 (Android 7.0), Android 7 and 8 devices are still in range, so don't skip this one.

iOS setup

Add a Face ID usage string to ios/Runner/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Unlock your saved notes with Face ID.</string>

Write the reason the user will read. Apple's sample code says the system shows this string the first time your app tries to use Face ID, and that without the key "the system won't allow your app to use Face ID." Touch ID doesn't need a usage string.

Check what the device supports

local_auth has three capability checks, and they answer different questions:

• canCheckBiometrics: does the device have biometric hardware?
• isDeviceSupported(): can the device authenticate the user at all, biometric or passcode?
• getAvailableBiometrics(): which biometrics are enrolled right now?

The README's own warning is worth repeating: canCheckBiometrics only means the hardware exists, not that a face or finger is enrolled.

import 'package:local_auth/local_auth.dart';

final LocalAuthentication auth = LocalAuthentication();

Future<bool> canOfferBiometricUnlock() async {
  if (!await auth.isDeviceSupported()) return false;
  final List<BiometricType> enrolled = await auth.getAvailableBiometrics();
  return enrolled.isNotEmpty;
}

Use this to decide whether to show the "Unlock with Face ID" switch in settings at all. The README suggests you check that something is enrolled rather than which type: types are device-specific, and Android often reports BiometricType.strong or BiometricType.weak rather than face or fingerprint.

Authenticate the user

Future<bool> unlock() async {
  try {
    return await auth.authenticate(
      localizedReason: 'Unlock your saved notes',
      biometricOnly: false,
      persistAcrossBackgrounding: true,
    );
  } on LocalAuthException catch (e) {
    return handleAuthError(e);
  }
}

What each parameter does in 3.x:

• localizedReason: the text in the prompt. It must not be empty.
• biometricOnly: true blocks the passcode, PIN and pattern fallback. It isn't supported on Windows, because Windows Hello doesn't let apps choose the method.
• persistAcrossBackgrounding: if the system cancels the prompt because the app went to the background (a phone call, a notification tapped by accident), the plugin waits and retries when the app comes back. This is the old stickyAuth.
• sensitiveTransaction: defaults to true. It enables platform precautions such as a confirm step after face unlock on some Android devices. Leave it on for payments, and consider false for a simple app lock.
• authMessages: per-platform dialog text, using AndroidAuthMessages and IOSAuthMessages from the platform packages.

Should you set biometricOnly: true? Only if the passcode would be a weaker check than you can accept. For an app lock, the device passcode is the same secret that unlocks the phone, so allowing it is reasonable. It also means someone whose fingerprint stopped working can still get in.

LocalAuthException codes and what to do with each

A failed match (wrong finger, face not recognized) returns false without throwing. Most other outcomes throw LocalAuthException. These are the codes in local_auth_platform_interface 1.1.0:

A handler that covers the cases users actually hit:

bool handleAuthError(LocalAuthException e) {
  switch (e.code) {
    case LocalAuthExceptionCode.userCanceled:
    case LocalAuthExceptionCode.systemCanceled:
      return false;
    case LocalAuthExceptionCode.noBiometricsEnrolled:
    case LocalAuthExceptionCode.noCredentialsSet:
    case LocalAuthExceptionCode.noBiometricHardware:
      showMessage('Biometric unlock isn\'t set up on this device. Sign in with your password instead.');
      return false;
    case LocalAuthExceptionCode.temporaryLockout:
    case LocalAuthExceptionCode.biometricLockout:
      showMessage('Too many attempts. Use your passcode or try again shortly.');
      return false;
    default:
      debugPrint('local_auth failed: ${e.code} ${e.description}');
      return false;
  }
}

showMessage stands in for whatever your app uses: a SnackBar, a dialog or an inline error.

Common errors and their fixes

The prompt never appears on Android and you get uiUnavailable. MainActivity still extends FlutterActivity. Switch it to FlutterFragmentActivity and rebuild. A hot restart isn't enough, because this is native code.

The app crashes on an Android 8 device when the prompt opens. The launch theme isn't an AppCompat theme. Set the LaunchTheme parent to Theme.AppCompat.DayNight.

Face ID never works on iOS, even though Touch ID devices are fine. NSFaceIDUsageDescription is missing from Info.plist. Without it, the system won't let your app use Face ID. Add the key and reinstall the app.

canCheckBiometrics is true but authentication throws noBiometricsEnrolled. That's expected: it checks hardware, not enrollment. Use getAvailableBiometrics() before you show the option.

Old code doesn't compile: The named parameter 'options' isn't defined. You're on 3.x with a 2.x snippet. Move biometricOnly up a level and rename stickyAuth to persistAcrossBackgrounding.

The prompt disappears when a notification arrives. The system canceled it. Set persistAcrossBackgrounding: true, or handle systemCanceled by offering a retry.

Nothing happens in the iOS Simulator. Enable Face ID under Features → Face ID → Enrolled, then use Matching Face or Non-matching Face to answer the prompt. On an Android emulator, add a fingerprint in the emulator's system settings, then use the Fingerprint section of the Extended Controls panel to touch the sensor.

Biometrics gate the UI, they don't encrypt anything

This is the part most tutorials skip. authenticate() returns a bool. If your app keeps a refresh token in shared_preferences and shows the home screen when that bool is true, the token is still in plain storage. Someone with a rooted device or a backup of the app's files can read it without ever seeing your Face ID prompt.

A biometric lock does its job when the thing behind it is also protected:

1. Store secrets (tokens, keys) with flutter_secure_storage, which uses the Android Keystore and the iOS/macOS Keychain. Its README documents AndroidOptions.biometric(), which ties a value to biometric authentication on Android (API 23+). It also documents iOS accessibility options for when Keychain values can be read.
2. Use local_auth for the app-lock moment: when the app opens or returns from the background after a set time.
3. Keep a non-biometric way back in, such as the account password. Biometrics get locked out, sensors break and people get new phones.

For a notes app, a lock screen built on local_auth alone is fine. For banking, health or anything where the token is the real prize, put the token behind the keystore too.

Biometric lock in an app built with FlutterGo

If you build the app with FlutterGo, the AI Flutter app builder, you can ask for this in plain English: "Add a Face ID / fingerprint lock when the app opens, with the account password as a fallback, and keep the session token in secure storage." The generated project is a normal Flutter project, so the same rules apply. Check that MainActivity extends FlutterFragmentActivity, that Info.plist has NSFaceIDUsageDescription, and that the catch block handles LocalAuthException, not PlatformException. Biometrics need a real device or an emulator with enrolled biometrics, so test the lock outside the browser preview. For the other runtime prompts your app may need, see our guide to Flutter permissions in 2026.

FAQ

Sources

• local_auth on pub.dev (version, platforms, likes, downloads), checked October 6, 2026
• local_auth README and 3.0.0 changelog, flutter/packages
• local_auth_android setup and local_auth_darwin setup
• LocalAuthExceptionCode source, local_auth_platform_interface 1.1.0
• flutter_secure_storage on pub.dev, 11.2.0, checked October 6, 2026
• NSFaceIDUsageDescription and Logging a User into Your App with Face ID or Touch ID, Apple Developer Documentation
• USE_BIOMETRIC permission, Android Developers

• flutter biometric authentication
• local_auth
• face id flutter
• fingerprint flutter
• flutter_secure_storage
• flutter