Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/auth0/nextjs-auth0/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

SdkError is the abstract base class for all errors thrown by the Auth0 Next.js SDK. All SDK error classes extend from this base class and include a code property that identifies the specific error type.

​
Class Definition

export abstract class SdkError extends Error {
  public abstract code: string;
}

​
Properties

​
code
string
required
A unique string identifier for the error type. Use this property to programmatically handle different error scenarios instead of using instanceof checks.
​
message
string
required
A human-readable error message inherited from the JavaScript Error class.
​
name
string
required
The name of the error class (e.g., "AccessTokenError", "AuthorizationError"). Inherited from the JavaScript Error class.

​
Error Hierarchy

All SDK errors extend from SdkError: 
SdkError (abstract base)
├── OAuth2Error
├── DiscoveryError
├── MissingStateError
├── InvalidStateError
├── InvalidConfigurationError
├── AuthorizationError
├── AuthorizationCodeGrantRequestError
├── AuthorizationCodeGrantError
├── BackchannelLogoutError
├── BackchannelAuthenticationNotSupportedError
├── BackchannelAuthenticationError
├── AccessTokenError
├── AccessTokenForConnectionError
├── CustomTokenExchangeError
├── DPoPError
├── MfaGetAuthenticatorsError
├── MfaChallengeError
├── MfaVerifyError
├── MfaNoAvailableFactorsError
├── MfaEnrollmentError
├── MfaRequiredError
├── MfaTokenExpiredError
├── MfaTokenInvalidError
└── InvalidRequestError

​
Error Handling Pattern

The recommended approach for handling SDK errors is to check the code property rather than using instanceof checks: 
import { getAccessToken } from '@auth0/nextjs-auth0/server';

try {
  const { accessToken } = await getAccessToken();
} catch (error) {
  // Check if it's an SDK error by checking for the code property
  if (error && typeof error === 'object' && 'code' in error) {
    switch (error.code) {
      case 'missing_session':
        // Handle missing session
        redirect('/auth/login');
        break;
      case 'missing_refresh_token':
        // Handle missing refresh token
        console.error('Refresh token not available');
        break;
      case 'failed_to_refresh_token':
        // Handle refresh failure
        redirect('/auth/login');
        break;
      default:
        console.error('Unknown error:', error.code);
    }
  } else {
    // Handle non-SDK errors
    throw error;
  }
}

​
Importing Errors

All error classes are exported from the @auth0/nextjs-auth0/errors package: 
import {
  SdkError,
  AccessTokenError,
  AuthorizationError,
  MfaRequiredError,
  // ... other error classes
} from '@auth0/nextjs-auth0/errors';

​
Type Safety

For TypeScript users, you can use type guards to narrow error types: 
import { SdkError, AccessTokenError } from '@auth0/nextjs-auth0/errors';

function isSdkError(error: unknown): error is SdkError {
  return error instanceof Error && 'code' in error;
}

function isAccessTokenError(error: unknown): error is AccessTokenError {
  return isSdkError(error) && error.name === 'AccessTokenError';
}

try {
  await getAccessToken();
} catch (error) {
  if (isAccessTokenError(error)) {
    console.error(`Access token error [${error.code}]:`, error.message);
  }
}

​
Best Practices

✓ Use error codes

Always check the code property to identify specific error types. This is more reliable than instanceof checks.

✓ Handle specific errors

Handle specific error codes that are relevant to your application flow rather than catching all errors generically.

✗ Avoid instanceof

Don’t rely on instanceof checks for error handling. Use the code property instead.

✗ Don't expose sensitive data

Some error messages (like OAuth2Error) may contain reflected user input. Never render error messages directly without proper escaping.

Build docs developers (and LLMs) love

Get started for freeTalk to us