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 A unique string identifier for the error type. Use this property to programmatically handle different error scenarios instead of using instanceof checks.
A human-readable error message inherited from the JavaScript Error class.
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.
