SdkError

Base class for all Auth0 Next.js SDK errors

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.

Related

• OAuth Errors - OAuth 2.0 and OIDC related errors
• DPoP Errors - DPoP-specific errors
• MFA Errors - Multi-factor authentication errors