Skip to content
mera
Get startedGetting started →

Errors

The library uses MeraError for its documented failure modes. It carries a stable, machine-readable code alongside the usual message and optional cause. The codes are the contract; the message text is free to change between versions.

MeraError

Section titled “MeraError”
declare class 
class MeraError
MeraError extends 
var Error: ErrorConstructor
Error {
  readonly 
MeraError.code: MeraErrorCode
code: 
type MeraErrorCode = "PASSKEY_OPERATION_FAILED" | "PASSKEY_CANCELLED" | "CRYPTO_UNAVAILABLE" | "PRF_UNAVAILABLE" | "SESSION_ENDED" | "DECRYPT_FAILED" | "INPUT_INVALID" | "VAULT_FORMAT_INVALID"
Stable error codes thrown by this package.


    

  • PASSKEY_OPERATION_FAILED: WebAuthn failed, returned an unexpected credential, or the credential API is unavailable.
    • 

  • PASSKEY_CANCELLED: the person dismissed the passkey prompt, it timed out, or no passkey answered.
    • 

  • CRYPTO_UNAVAILABLE: the runtime lacks a needed Web Crypto primitive. The passkey APIs need crypto.getRandomValues; the secret-vault APIs also need crypto.subtle.
    • 

  • PRF_UNAVAILABLE: the authenticator did not enable or return a usable 32-byte WebAuthn PRF output.
    • 

  • SESSION_ENDED: a signing call was made after end().
    • 

  • DECRYPT_FAILED: AES-GCM authentication failed (wrong key or tampered nonce/ciphertext).
    • 

  • INPUT_INVALID: a caller-supplied value at a public boundary did not satisfy a length, range, encoding, or curve (scalar or point) constraint.
    • 

  • VAULT_FORMAT_INVALID: untrusted vault data (JSON or object) was malformed, missing required fields, used a non-canonical encoding, or declared an unsupported version.
    • 

MeraErrorCode;
}

name is always "MeraError". When a lower-level failure triggered the error (a WebAuthn rejection, a Web Crypto failure), it is attached as cause.

instanceof MeraError narrows a caught value so code can be branched on:

import {
  
function getPasskeyPrfOutput({ rpId, credential: allowCredential, prfSalt, timeout, immediate, webAuthnClient, }: getPasskeyPrfOutput.Options): Promise<getPasskeyPrfOutput.Result>
Requests a passkey PRF evaluation and returns the first output.
@param ― options - Passkey PRF request inputs.
@returns ― The selected credential ID and first WebAuthn PRF output.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.


With immediate, Chrome 148 and later (as of 2026-10) and the React Native
client show nothing when the device holds no passkey for rpId. Browsers
without immediate mode ignore the option and show their usual prompt.
Without a user gesture, or in Incognito, Chrome rejects an immediate request
with the same error even when a passkey exists.


The WebAuthn challenge is generated internally.


The default salt is sha256("mera.prf.salt.v1") and will not change across
library versions. The PRF output is a deterministic function of the
credential, rpId, and salt; a different salt yields an unrelated output.


The assertion requires user verification, and the requirement is not
configurable. User verification is the authenticator's local check; the
gesture depends on the platform (a biometric, a device PIN, or a password).
Authenticators built on CTAP's hmac-secret keep two PRFs per credential,
one for user-verified requests and one for the rest; WebAuthn exposes only
the user-verified PRF and overrides a weaker userVerification setting
when evaluating it, so a configurable setting could neither change the PRF
output nor skip the check.
@see ― https://www.w3.org/TR/webauthn-3/#prf-extension WebAuthn: the PRF extension
@see ― https://www.w3.org/TR/webauthn-3/#enumdef-userverificationrequirement WebAuthn: UserVerificationRequirement
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when an explicit prfSalt is not 32 bytes, credential.credentialId is empty or not canonical base64url, or immediate is combined with credential.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues is unavailable.
@throws ― MeraError with code PASSKEY_CANCELLED when the person dismisses the prompt, it times out, or no passkey answers, including an immediate request that finds none.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, fails for another reason, or returns an unexpected credential.
getPasskeyPrfOutput,
  
class MeraError
Error thrown by this package.
MeraError,
} from "@category-labs/mera";


try {
  await 
function getPasskeyPrfOutput({ rpId, credential: allowCredential, prfSalt, timeout, immediate, webAuthnClient, }: getPasskeyPrfOutput.Options): Promise<getPasskeyPrfOutput.Result>
Requests a passkey PRF evaluation and returns the first output.
@param ― options - Passkey PRF request inputs.
@returns ― The selected credential ID and first WebAuthn PRF output.
@remarks ― 
Runs one assertion ceremony and shows one user-verification prompt.


With immediate, Chrome 148 and later (as of 2026-10) and the React Native
client show nothing when the device holds no passkey for rpId. Browsers
without immediate mode ignore the option and show their usual prompt.
Without a user gesture, or in Incognito, Chrome rejects an immediate request
with the same error even when a passkey exists.


The WebAuthn challenge is generated internally.


The default salt is sha256("mera.prf.salt.v1") and will not change across
library versions. The PRF output is a deterministic function of the
credential, rpId, and salt; a different salt yields an unrelated output.


The assertion requires user verification, and the requirement is not
configurable. User verification is the authenticator's local check; the
gesture depends on the platform (a biometric, a device PIN, or a password).
Authenticators built on CTAP's hmac-secret keep two PRFs per credential,
one for user-verified requests and one for the rest; WebAuthn exposes only
the user-verified PRF and overrides a weaker userVerification setting
when evaluating it, so a configurable setting could neither change the PRF
output nor skip the check.
@see ― https://www.w3.org/TR/webauthn-3/#prf-extension WebAuthn: the PRF extension
@see ― https://www.w3.org/TR/webauthn-3/#enumdef-userverificationrequirement WebAuthn: UserVerificationRequirement
@throws ― MeraError with code PRF_UNAVAILABLE when the authenticator does not return a usable 32-byte PRF output.
@throws ― MeraError with code INPUT_INVALID when an explicit prfSalt is not 32 bytes, credential.credentialId is empty or not canonical base64url, or immediate is combined with credential.
@throws ― MeraError with code CRYPTO_UNAVAILABLE when crypto.getRandomValues is unavailable.
@throws ― MeraError with code PASSKEY_CANCELLED when the person dismisses the prompt, it times out, or no passkey answers, including an immediate request that finds none.
@throws ― MeraError with code PASSKEY_OPERATION_FAILED when WebAuthn is unavailable, fails for another reason, or returns an unexpected credential.
getPasskeyPrfOutput({
    
rpId: string
Relying party ID for the WebAuthn assertion.
rpId: "account.example.com",
  });
} catch (
var error: unknown
error) {
  if (
var error: unknown
error instanceof 
class MeraError
Error thrown by this package.
MeraError && 
var error: MeraError
error.
MeraError.code: MeraErrorCode
Stable machine-readable category for the failure.
code === "PRF_UNAVAILABLE") {
    // Point at a PRF-capable authenticator.
  }
  throw 
var error: unknown
error;
}

Codes

Section titled “Codes”

PASSKEY_OPERATION_FAILED

Section titled “PASSKEY_OPERATION_FAILED”

WebAuthn failed, returned an unexpected credential, or the credential API is unavailable.

PASSKEY_CANCELLED

Section titled “PASSKEY_CANCELLED”

The person dismissed the passkey prompt, it timed out, or no passkey answered. Dismissal is the everyday case. Browsers report all three with the same NotAllowedError, so they cannot be told apart.

CRYPTO_UNAVAILABLE

Section titled “CRYPTO_UNAVAILABLE”

A Web Crypto primitive is unavailable. The passkey APIs need crypto.getRandomValues; the secret-vault APIs also need crypto.subtle (requires HTTPS or localhost during development).

PRF_UNAVAILABLE

Section titled “PRF_UNAVAILABLE”

The authenticator did not enable PRF, or did not return a usable 32-byte PRF output. Authenticator support lists tested compatible stacks.

SESSION_ENDED

Section titled “SESSION_ENDED”

A signing call was made after the session’s end().

DECRYPT_FAILED

Section titled “DECRYPT_FAILED”

AES-GCM authentication failed while decrypting a vault: wrong key material or a tampered nonce/ciphertext pair.

INPUT_INVALID

Section titled “INPUT_INVALID”

A caller-supplied value at a public boundary did not satisfy a length, range, encoding, or curve constraint (a private key that is not a valid scalar, a public key that is not a valid point). Each function’s Errors section lists its specific conditions.

VAULT_FORMAT_INVALID

Section titled “VAULT_FORMAT_INVALID”

Untrusted vault data (JSON text or an object) was malformed, missing required fields, used a non-canonical encoding, or declared an unsupported version.