Error Handling - With AutoLogin

This guide only applies if you have enabled Auto Login. If you do not have Auto Login enabled, follow this guide instead.

Here is how you can gracefully handle oidc initialization errors:

Framework Agnostic

import { createOidc, type OidcInitializationError } from "oidc-spa/core";

const oidc = await createOidc({
    // ...
    autoLogin: true
})
// In autoLogin: false, createOidc never throws.
// In autoLogin: true, it can throw — but only OidcInitializationError —
// so you can safely narrow/cast here.
.catch(error => error as OidcInitializationError);

if( oidc instanceof Error ){

    const oidcInitializationError = oidc;
    
    // Use this to distinguish a misconfiguration from a temporary auth-server outage.
    // NOTE: below references should use `oidcInitializationError`.
    console.log(initializationError.isAuthServerLikelyDown);
    
    // Developer-only diagnostic with likely cause and fix.
    // Do not display this to end users.
    console.log(initializationError.message);
    
    alert("Our auth is down, sorry :(");
    
    // Halt the app in a typed-safe way (nothing renders until you decide otherwise).
    await Promise<never>(()=>{});
}

TanStack Start

React SPAs

Angular