Fixing Biometric Prompt Not Working in Kotlin

If you’re developing an Android app using Kotlin and trying to implement biometric authentication using BiometricPrompt, it’s common to encounter issues such as the prompt not showing, failing to authenticate, or throwing unexpected errors.

In this guide, we will walk through the most common causes of “Biometric Prompt not working in Kotlin” and how to fix them step-by-step with a real working example.

Understanding BiometricPrompt

The BiometricPrompt API provides a unified way to authenticate users using biometrics such as fingerprint, face recognition, or iris scan. It’s available from Android 9 (API level 28), with backward compatibility using AndroidX Biometric library.

Before diving into the fix, make sure you’ve added the right dependency in your build.gradle:

dependencies {
    implementation "androidx.biometric:biometric:1.2.0-alpha04"
}

Common Issues and Fixes

1. Missing Permissions

Biometric prompt won’t work if the app doesn’t have the necessary permissions.

Fix: Add this to your AndroidManifest.xml:

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

Note: USE_FINGERPRINT is required for backward compatibility.

2. Biometric Not Enrolled

Biometric prompt won’t show if the user hasn’t enrolled any fingerprint or face data.

Fix: Check if biometric is enrolled before invoking the prompt.

val biometricManager = BiometricManager.from(this)
when (biometricManager.canAuthenticate(BIOMETRIC_STRONG)) {
    BiometricManager.BIOMETRIC_SUCCESS -> Log.d("Biometric", "Can authenticate")
    BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> Log.e("Biometric", "No biometric features available")
    BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> Log.e("Biometric", "Biometric features are currently unavailable")
    BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> Log.e("Biometric", "No biometric credentials enrolled")
}

3. Incorrect Context Usage

Using the wrong context or fragment can lead to the biometric prompt not appearing.

Fix: Make sure you are calling BiometricPrompt from a valid FragmentActivity or Fragment.

Working Example in Kotlin

Below is a complete Kotlin example that uses BiometricPrompt with proper error handling and callbacks:

class MainActivity : AppCompatActivity() {

    private lateinit var biometricPrompt: BiometricPrompt
    private lateinit var promptInfo: BiometricPrompt.PromptInfo

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val executor = ContextCompat.getMainExecutor(this)

        biometricPrompt = BiometricPrompt(this, executor,
            object : BiometricPrompt.AuthenticationCallback() {
                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                    super.onAuthenticationSucceeded(result)
                    Toast.makeText(applicationContext, "Authentication succeeded!", Toast.LENGTH_SHORT).show()
                }

                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                    super.onAuthenticationError(errorCode, errString)
                    Toast.makeText(applicationContext, "Authentication error: $errString", Toast.LENGTH_SHORT).show()
                }

                override fun onAuthenticationFailed() {
                    super.onAuthenticationFailed()
                    Toast.makeText(applicationContext, "Authentication failed", Toast.LENGTH_SHORT).show()
                }
            })

        promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle("Biometric login for MyApp")
            .setSubtitle("Log in using your biometric credential")
            .setNegativeButtonText("Use account password")
            .build()

        val loginButton: Button = findViewById(R.id.loginButton)
        loginButton.setOnClickListener {
            biometricPrompt.authenticate(promptInfo)
        }
    }
}

Layout File (activity_main.xml)

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <Button
        android:id="@+id/loginButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Login with Biometrics"
        android:layout_centerInParent="true"/>
</RelativeLayout>

Tips for Smooth Biometric Implementation

• Always check for device compatibility.
• Use fallbacks like PIN/password if biometrics are not available.
• Test on both API 28+ and lower versions (with BiometricPromptCompat).
• Use BiometricManager.canAuthenticate() before attempting to prompt.

Conclusion

When the BiometricPrompt not working issue in Kotlin arises, it’s usually due to missing permissions, incorrect context, or unregistered biometrics. With proper setup and error handling, the biometric prompt can be a seamless and secure way to authenticate users.

For more details, you can refer to the official AndroidX biometric documentation. Tips for Smooth Biometric Implementation

• Always check for device compatibility.
• Use fallbacks like PIN/password if biometrics are not available.
• Test on both API 28+ and lower versions (with BiometricPromptCompat).
• Use BiometricManager.canAuthenticate() before attempting to prompt.

Conclusion

When the BiometricPrompt not working issue in Kotlin arises, it’s usually due to missing permissions, incorrect context, or unregistered biometrics. With proper setup and error handling, the biometric prompt can be a seamless and secure way to authenticate users.