Error Handling - With AutoLogin

In Auto Login mode, there is no “fallback” unauthenticated experience if oidc-spa fails to initialize, so error handling is different.

We expose separate hooks/components so you can handle initialization errors gracefully and render a clear, user-facing message while keeping diagnostics in the console for developers.

In autoLogin: false, createOidc never throws (if it does, that’s a bug). In autoLogin: true, createOidc may throw only an OidcInitializationError, which includes:

isAuthServerLikelyDown: helps you distinguish a temporary outage from a misconfiguration.
message: a developer-oriented diagnostic (do not show this to end users).

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>(()=>{});
}

src/routes/__root.tsx

import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";

import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import { OidcInitializationGate } from "@/oidc";
import type { OidcInitializationError } from "oidc-spa/core";

export const Route = createRootRoute({
    // ...
    shellComponent: RootDocument
});

function RootDocument({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en">
            <head>
                <HeadContent />
            </head>
            <body>
                <div className="min-h-screen flex flex-col">
                    <Header />
                    <main className="flex flex-1 flex-col">
                        <OidcInitializationGate 
                            pendingComponent={()=> <Spinner />}
                            errorComponent={OidcErrorComponent}
                        >
                            {children}
                        </OidcInitializationGate>
                    </main>
                </div>
                <AutoLogoutWarningOverlay />
                <Scripts />
            </body>
        </html>
    );
}

function OidcErrorComponent(props: { 
    oidcInitializationError: OidcInitializationError;
}){
    const { oidcInitializationError } = props;
    
    // Distinguish misconfiguration vs. temporary auth-server outage.
    console.log(oidcInitializationError.isAuthServerLikelyDown);

    // Developer-only diagnostic with likely cause and fix.
    // Do not display this to end users.
    console.log(oidcInitializationError.message);

    return <h1>Our auth is down, sorry</h1>;
    
}

src/oidc.ts

import { oidcSpa } from "oidc-spa/react-spa";

export const {
    bootstrapOidc,
    useOidc,
    getOidc,
    OidcInitializationGate,
    OidcInitializationErrorGate
} = oidcSpa
    .withExpectedDecodedIdTokenShape({ /* ... */ }),
    .withAutoLogin()
    .createUtils();

import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App";
import { 
    OidcInitializationGate, 
    OidcInitializationErrorGate 
} from "~/oidc";
import type { OidcInitializationError } from "oidc-spa/core";

ReactDOM.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
        <OidcInitializationGate>
            <OidcInitializationErrorGate errorComponent={OidcErrorComponent} >
                <App />
            </OidcInitializationErrorGate>
        </OidcInitializationGate>
    </React.StrictMode>
);

function OidcErrorComponent(props: { 
    oidcInitializationError: OidcInitializationError;
}){
    const { oidcInitializationError } = props;
    
    // Distinguish misconfiguration vs. temporary auth-server outage.
    console.log(oidcInitializationError.isAuthServerLikelyDown);

    // Developer-only diagnostic with likely cause and fix.
    // Do not display this to end users.
    console.log(oidcInitializationError.message);

    return <h1>Our auth is down, sorry</h1>;
    
}

src/app/app.html

@if (oidc.initializationError) {
<h1>Our Auth is down, sorry :(</h1>
}@else{
<!-- Your app -->
}

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, RouterLink, RouterLinkActive],
  templateUrl: './app.html',
})
export class App {
  oidc = inject(Oidc);

  constructor(){

    if( this.oidc.initializationError ){

      const { initializationError } = this.oidc;

      // Distinguish a misconfiguration from a temporary auth-server outage.
      console.log(initializationError.isAuthServerLikelyDown);

      // Developer-only diagnostic with likely cause and fix.
      // Do not display this to end users.
      console.log(initializationError.message);

    }

  }
}

PreviousError Handling - No AutoLogin NextNon Blocking Rendering

Last updated 9 days ago

Was this helpful?