Debug and Error Handling

Gracefully handle authentication issues

What happens if your OIDC server is down or misconfigured? This guide explains how to debug your setup during development and handle errors gracefully in production.

---

Debugging in Development

To better understand what’s going on under the hood, enable debug logs in your configuration. This will print detailed information to your browser console about OIDC initialization, token validation, and redirects.

Framework Agnostic

src/oidc.ts

createOidc({ 
  // ...
  debugLogs: true 
});

React

Angular

Once enabled, make sure to check "Preserve Log" in your browser’s console options so the logs aren’t cleared during redirects.

Here’s a common example: If you see a message like this in the console, it usually means your Valid Redirect URIs list in your IdP configuration is incomplete:

In this case, simply add http://localhost:3000/ (or the appropriate URL for your environment) to your list of valid redirect URIs in the IdP settings.

---

Gracefully Handling Errors in Production

How your app should react to authentication issues depends on whether Auto Login is enabled.

See the following sections for best practices and code examples:

Error Handling - No AutoLoginError Handling - With AutoLogin