---
title: "Troubleshooting"
manual: "Passkeys Frontend Authentication"
version: "2.0"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-passkeys-fe:troubleshooting@2.0"
source: "Troubleshooting/Index.rst"
rendered: "2026-09-29T22:18:36+00:00"
---

# Troubleshooting {#troubleshooting}

This page covers the most common issues encountered when setting up or
using the extension.

## "Not allowed" / SecurityError in browser {#not-allowed-securityerror-in-browser}

**Symptom:** The browser throws `NotAllowedError` or similar when
attempting passkey login or enrollment.

**Causes and fixes:**

1.  **Not on HTTPS.** WebAuthn requires HTTPS. Exception: `localhost`
    works over HTTP for development. Check your URL.
1.  **Wrong RP ID.** The configured `rpId` must match the current
    domain. If `rpId: 'example.com'` but the page is served from
    `sub.example.com`, registration will fail unless the RP ID is
    the registrable suffix.
1.  **User cancelled the prompt.** The user dismissed the authenticator
    dialog. Not a server error.
1.  **Cross-origin iframe.** WebAuthn cannot be invoked from a
    cross-origin iframe. Ensure the login plugin is on the same origin
    as the page.

## Challenge expired {#challenge-expired}

**Symptom:** Login fails with "Challenge token expired or invalid."

**Fix:** The challenge TTL is 120 seconds by default. If users take
longer to authenticate (e.g. slow hardware key), increase
`challengeTtlSeconds` in the extension settings.

## "Invalid origin" error in logs {#invalid-origin-error-in-logs}

**Symptom:** Authentication fails with an origin mismatch in the
TYPO3 logs.

**Fix:** The `passkeys.origin` in the site's `config.yaml` must
exactly match the scheme + domain + port combination the browser sees.
Include the port if non-standard (e.g. `https://example.com:8443`).

## Account locked {#account-locked}

**Symptom:** User sees "Account locked" after multiple failed attempts.

**Fix:** Wait for the lockout duration to expire (default: 15 minutes),
or unlock via the backend module:
**Admin Tools > Passkey Management FE > Users**.

## Login plugin shows no passkey button {#login-plugin-shows-no-passkey-button}

**Symptom:** The login page shows the standard felogin form but no
passkey button.

**Checklist:**

1.  Is `nr_passkeys_fe` activated? Check
    **Admin Tools > Extensions**.
1.  Is the NrPasskeysFe:Login plugin (not felogin) added to the page?
1.  Is TypoScript included? Check
    **Web > Template > TypoScript Object Browser**.
1.  Are there JavaScript errors in the browser console?

## Recovery codes not accepted {#recovery-codes-not-accepted}

**Symptom:** Recovery code login fails with "Invalid recovery code."

**Causes:**

1.  The code was already used. Each code is one-time only.
1.  The user generated a new set, invalidating all previous codes.
1.  The code was entered incorrectly (check for `0` vs `O`,
    `1` vs `l`).

## Enrollment interstitial appears after every login {#enrollment-interstitial-appears-after-every-login}

**Symptom:** User is redirected to the enrollment page on every login
even after enrolling.

**Causes:**

1.  The enrolled credential's `site_identifier` does not match the
    current site. This can happen if the RP ID was changed after
    enrollment.
1.  The TYPO3 `SYS.encryptionKey` was changed, invalidating the
    `user_handle` lookup.

**Fix:** Have the user revoke the old credential and re-enroll. If
`encryptionKey` was changed, all credentials must be re-enrolled.

## Debug logging {#debug-logging}

Enable TYPO3 debug logging to see detailed authentication errors:

**config/system/additional.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['LOG']['Netresearch']['NrPasskeysFe'] = [
    'writerConfiguration' => [
        \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [
            \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
                'logFileInfix' => 'nr_passkeys_fe',
            ],
        ],
    ],
];
```

Log file: `var/log/typo3_nr_passkeys_fe_*.log`