# Error Handling - With AutoLogin {% hint style="info" %} This guide only applies if you have enabled [Auto Login](/features/auto-login.md).\ If you do **not** have Auto Login enabled, follow [this guide instead](/features/error-management/error-handling-no-autologin.md). {% endhint %} Here is how you can gracefully handle oidc initialization errors: {% tabs %} {% tab title="Framework Agnostic" %} ```typescript 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(()=>{}); } ``` {% endtab %} {% tab title="TanStack Start" %}

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

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

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

function RootDocument({ children }: { children: React.ReactNode }) {

    const { oidcInitializationError } = useOidc();

    return (
        <html lang="en">
            <head>
                <HeadContent />
            </head>
            <body>
                <div className="min-h-screen flex flex-col">
                    <Header />
                    <main className="flex flex-1 flex-col">
                        {oidcInitializationError ? (
                            <OidcErrorComponent oidcInitializationError={oidcInitializationError} />
                        ) : (
                            children
                        )}
                    </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>;
    
}

{% endtab %} {% tab title="React SPAs" %}

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>;
    
}

{% endtab %} {% tab title="Angular" %} {% code title="src/app/app.html" %} ```html @if (oidc.initializationError) {

Our Auth is down, sorry :(

}@else{ } ``` {% endcode %}

@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);

    }

  }
}

{% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.oidc-spa.dev/features/error-management/error-handling-with-autologin.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.