Skip to main content

Troubleshooting

Module not initialized​

Make sure @quik/passport is registered in your bootstrap module and appears after its dependencies (@quik/http-express, @quik/authorization, @quik/entity). Passport middleware, strategies, and OAuth providers are only wired up in onAfterInit when the IQHTTPEngine feature is present.

Passkey routes return 404​

QPasskeyRoute is registered unconditionally, but its endpoints are gated by @Decorators.Route.Utils.Conditional(() => getConfig().boolean("auth.passkey.http.enabled")). Set auth.passkey.http.enabled to true to expose the built-in /register/options, /register/verify, /authenticate/options, and /authenticate/verify endpoints under auth.passkey.http.basePath.

Passkey provider not registered​

Calling Passport.Passkey.createRegistrationOptions/verifyAuthentication/etc. without first calling Passport.Passkey.setProvider(...) for the relevant provider name throws PasskeyProviderNotRegisteredError.

Invalid passkey request or assertion​

InvalidPasskeyRequestError is thrown when a passkey authentication/registration request payload is malformed. InvalidPasskeyAssertionError is thrown when a WebAuthn assertion fails verification.

Common Errors​

  • quik.errors.passkey.provider-not-registered: Passport.Passkey.setProvider(...) was not called for the requested provider name before use.
  • quik.errors.passkey.invalid-request: a passkey authentication request payload is invalid.
  • quik.errors.passkey.invalid-assertion: a WebAuthn assertion failed verification.