Enum ClerkError 

#[non_exhaustive]
pub enum ClerkError {
    NotLoaded,
    Timeout(String),
    UnsupportedTarget,
    ScriptLoad(String),
    Offline,
    Unauthenticated,
    TokenExpired,
    JwksUnavailable(String),
    NoServerContext,
    InvalidConfig(String),
    NeedsReverification {
        level: Option<ReverificationLevel>,
    },
    ReverificationCancelled,
    Js(String),
}

Errors produced anywhere in the dioxus-clerk stack.

Variants store only owned strings (no JsValue, no transport-specific error sources) so this crate stays target-neutral, and errors stay Clone + PartialEq + Eq for signal storage and test assertions. This is a deliberate design: causes are flattened into the message at the boundary where they occur, and Error::source() is always None. Conversion impls live in the consumer modules.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NotLoaded

Clerk-js has not finished loading yet.

Timeout(String)

The browser Clerk lifecycle could not make progress before a deadline: a hung Clerk.load(), or a lifecycle that never started. Distinct from ClerkError::NotLoaded, which is the transient still-loading state a caller can wait out.

UnsupportedTarget

A browser-only Clerk action was awaited on a target where clerk-js can never load (server or native builds).

ScriptLoad(String)

The clerk-js script failed to load or did not become ready in time.

Offline

The browser is offline, so clerk-js could not fetch a fresh session token.

clerk-js 6 throws ClerkOfflineError from session.getToken() in this case, where 5.x returned null. Surfaced as a distinct, transient variant so callers can retry or fall back to a cached token instead of treating it as a hard failure or a signed-out state.

Unauthenticated

Request has no session/credentials.

TokenExpired

Session JWT is past its exp claim.

JwksUnavailable(String)

Server could not fetch or refresh JWKS from Clerk’s Backend API.

The message is intentionally coarse: this error’s Display can reach HTTP responses. The verification layer logs the underlying cause at warn level via tracing.

NoServerContext

A server context reader was called outside a server function or SSR scope.

InvalidConfig(String)

Configuration was invalid (missing key, malformed env, etc.).

NeedsReverification

A gated action needs step-up reverification: the user must re-assert a fresh authentication factor before it can proceed. Carries the required ReverificationLevel when clerk reported one.

Consumed by the reverification hook to trigger a re-auth prompt and resume the action. Produced from either clerk reverification signal:

• the server-side path: a gated #[server] action surfaces a 403 reverification hint (JSON), which ClerkError::from_reverification_hint maps, recovering the level;
• the client-side path: a direct clerk-js call throws a ClerkAPIResponseError carrying the session_reverification_required code, which a caller maps into this variant. The throw does not carry the level, so that path yields level: None, matching clerk-react’s useReverification.

Fields

level: Option<ReverificationLevel>

The authentication-factor level the reverification requires, when clerk reported one.

ReverificationCancelled

The user dismissed the step-up reverification prompt without completing it, so the gated action did not run. Mirrors clerk-js’s reverification_cancelled runtime error.

Js(String)

JS interop failure (wasm-bindgen / clerk-js threw).

Implementations

impl ClerkError

pub fn from_reverification_hint(value: &Value) -> Option<Self>

Recognize a clerk step-up reverification hint and map it to ClerkError::NeedsReverification, carrying the required level.

A gated #[server] action (or any caller reading a clerk API response as JSON) hits a 403 reverification hint of the shape emitted by clerk’s clerk_render_reverification and recognized by @clerk/shared’s isReverificationHint:

{ "clerk_error": {
    "type": "forbidden",
    "reason": "reverification-error",
    "metadata": { "reverification": { "level": "second_factor" } } } }

Returns None for any value that is not such a hint, so a caller can map only the reverification case and pass every other error through unchanged.

Trait Implementations

impl Clone for ClerkError

fn clone(&self) -> ClerkError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClerkError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ClerkError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for ClerkError

impl Error for ClerkError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ClerkError> for ServerFnError

Available on crate feature server only.

fn from(value: ClerkError) -> Self

Converts to this type from the input type.

impl From<InvalidTokenReason> for ClerkError

Maps a token-verification failure reason to the error callers act on.

Only InvalidTokenReason::Expired maps to ClerkError::TokenExpired; other reasons (including NotYetValid) collapse into ClerkError::Unauthenticated, because expiry is the one case callers can meaningfully act on (prompt a re-authentication).

fn from(reason: InvalidTokenReason) -> Self

Converts to this type from the input type.

impl PartialEq for ClerkError

fn eq(&self, other: &ClerkError) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ClerkError