OAuth Errors - Auth0 Next.js SDK

Overview

OAuth errors are thrown during various stages of the OAuth 2.0 and OpenID Connect authentication flows. All OAuth error classes extend from SdkError and can be caught using their specific error codes.

OAuth2Error

Generic OAuth 2.0 error from the authorization server. This error may contain reflected user input via OpenID Connect error and error_description query parameters.

Security Notice: Never render the message, error, or error_description properties without properly escaping them first, as they may contain reflected user input.

Properties

code

string

required

The OAuth 2.0 error code from the authorization server (e.g., "access_denied", "invalid_grant", "server_error").

message

string

required

Error message from the authorization server or the default message: “An error occurred while interacting with the authorization server.”

Usage

import { OAuth2Error } from '@auth0/nextjs-auth0/errors';

try {
  // OAuth flow operations
} catch (error) {
  if (error instanceof OAuth2Error) {
    console.error(`OAuth2 error [${error.code}]:`, error.message);
  }
}

DiscoveryError

Thrown when the SDK fails to retrieve the OpenID Connect configuration from the authorization server’s discovery endpoint.

Properties

code

string

required

Always "discovery_error"

message

string

required

Default: “Discovery failed for the OpenID Connect configuration.”

When Thrown

The authorization server’s .well-known/openid-configuration endpoint is unreachable
The discovery response is malformed or invalid
Network connectivity issues during discovery

Example

try {
  await auth0.login();
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'discovery_error') {
      console.error('Failed to discover OIDC configuration');
      // Check AUTH0_DOMAIN is correct
      // Verify network connectivity
    }
  }
}

MissingStateError

Thrown when the OAuth callback is missing the required state parameter.

Properties

code

string

required

Always "missing_state"

message

string

required

Default: “The state parameter is missing.”

When Thrown

The authorization server callback doesn’t include a state parameter
The callback URL was manipulated or corrupted

InvalidStateError

Thrown when the OAuth callback’s state parameter doesn’t match the expected value stored in the transaction.

Properties

code

string

required

Always "invalid_state"

message

string

required

Default: “The state parameter is invalid.”

When Thrown

CSRF attack attempt detected
State parameter was modified
Transaction cookie expired or was cleared
Multiple concurrent login attempts from the same browser

Example

try {
  await auth0.handleCallback(req);
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'invalid_state') {
      // Potential CSRF attack or expired transaction
      redirect('/auth/login?error=invalid_state');
    }
  }
}

InvalidConfigurationError

Thrown when the SDK is initialized with invalid configuration options.

Properties

code

string

required

Always "invalid_configuration"

message

string

required

Default: “The configuration is invalid.”

When Thrown

Missing required environment variables (AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_SECRET)
Invalid configuration values (e.g., malformed URLs, invalid algorithm)
Incompatible configuration combinations

Example

try {
  const auth0 = new Auth0Client({
    domain: '', // Invalid: empty domain
    clientId: 'abc123',
    clientSecret: 'secret',
    secret: 'cookie-secret'
  });
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'invalid_configuration') {
      console.error('SDK configuration is invalid:', error.message);
    }
  }
}

AuthorizationError

Thrown when an error occurs during the authorization flow. Contains the underlying OAuth2Error as its cause.

Properties

code

string

required

Always "authorization_error"

cause

OAuth2Error

required

The underlying OAuth 2.0 error from the authorization server.

message

string

required

Default: “An error occurred during the authorization flow.”

When Thrown

User denies authorization
Invalid scopes requested
Authorization server configuration issues

Example

try {
  await auth0.handleCallback(req);
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'authorization_error') {
      const authError = error as AuthorizationError;
      console.error('Authorization failed:', authError.cause.code);
      
      if (authError.cause.code === 'access_denied') {
        // User denied consent
        redirect('/auth/consent-required');
      }
    }
  }
}

AuthorizationCodeGrantRequestError

Thrown when preparing or performing the authorization code grant request fails.

Properties

code

string

required

Always "authorization_code_grant_request_error"

message

string

required

Default: “An error occurred while preparing or performing the authorization code grant request.”

When Thrown

Network errors during token exchange
Invalid request format
Authorization server unreachable

AuthorizationCodeGrantError

Thrown when the authorization code exchange fails. Contains the underlying OAuth2Error as its cause.

Properties

code

string

required

Always "authorization_code_grant_error"

cause

OAuth2Error

required

The underlying OAuth 2.0 error from the token endpoint.

message

string

required

Default: “An error occurred while trying to exchange the authorization code.”

When Thrown

Invalid authorization code
Expired authorization code
Code already used (replay attack)
Code verifier mismatch (PKCE)

Example

try {
  await auth0.handleCallback(req);
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'authorization_code_grant_error') {
      const grantError = error as AuthorizationCodeGrantError;
      
      if (grantError.cause.code === 'invalid_grant') {
        // Code expired or already used
        redirect('/auth/login?error=code_expired');
      }
    }
  }
}

BackchannelLogoutError

Thrown when completing a backchannel logout request fails.

Properties

code

string

required

Always "backchannel_logout_error"

message

string

required

Default: “An error occurred while completing the backchannel logout request.”

When Thrown

Invalid logout token
Signature verification fails
Session not found

BackchannelAuthenticationNotSupportedError

Thrown when attempting to use Client-Initiated Backchannel Authentication (CIBA) but the authorization server doesn’t support it.

Properties

code

string

required

Always "backchannel_authentication_not_supported_error"

message

string

required

“The authorization server does not support backchannel authentication. Learn how to enable it here: https://auth0.com/docs/get-started/applications/configure-client-initiated-backchannel-authentication”

When Thrown

CIBA is not enabled in your Auth0 tenant
OIDC discovery doesn’t include backchannel authentication endpoint

Example

try {
  await auth0.backchannelAuthentication({ loginHint: '[email protected]' });
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'backchannel_authentication_not_supported_error') {
      console.error('CIBA is not enabled for this tenant');
      // Fall back to standard authentication flow
      redirect('/auth/login');
    }
  }
}

BackchannelAuthenticationError

Thrown when a Client-Initiated Backchannel Authentication request fails.

Properties

code

string

required

Always "backchannel_authentication_error"

cause

OAuth2Error | undefined

The underlying OAuth 2.0 error, if available.

message

string

required

“There was an error when trying to use Client-Initiated Backchannel Authentication.”

When Thrown

Invalid login hint
User not found
Authentication device not available

AccessTokenError

Thrown when retrieving or refreshing an access token fails. See Access Token Error Codes for specific error codes.

Properties

code

string

required

One of: "missing_session", "missing_refresh_token", or "failed_to_refresh_token"

message

string

required

Error-specific message describing what went wrong.

cause

OAuth2Error | undefined

The underlying OAuth 2.0 error when code is "failed_to_refresh_token".

Access Token Error Codes

enum AccessTokenErrorCode {
  MISSING_SESSION = "missing_session",
  MISSING_REFRESH_TOKEN = "missing_refresh_token",
  FAILED_TO_REFRESH_TOKEN = "failed_to_refresh_token"
}

When Thrown

missing_session: No active session exists (user not logged in)
missing_refresh_token: Session exists but doesn’t contain a refresh token (offline_access scope not requested)
failed_to_refresh_token: Token refresh request failed (expired refresh token, revoked token, network error)

Example

import { getAccessToken } from '@auth0/nextjs-auth0/server';

try {
  const { accessToken } = await getAccessToken();
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    switch (error.code) {
      case 'missing_session':
        // Not logged in - redirect to login
        redirect('/auth/login');
        break;
      
      case 'missing_refresh_token':
        // No refresh token - need to re-authenticate
        console.error('Refresh token not available. Ensure offline_access scope is requested.');
        redirect('/auth/login');
        break;
      
      case 'failed_to_refresh_token':
        // Refresh failed - might be expired or revoked
        console.error('Failed to refresh token:', error.cause?.code);
        redirect('/auth/login');
        break;
    }
  }
}

AccessTokenForConnectionError

Thrown when retrieving or exchanging an access token for a specific connection fails.

Properties

code

string

required

One of: "missing_session", "missing_refresh_token", or "failed_to_exchange_refresh_token"

message

string

required

Error-specific message describing what went wrong.

cause

OAuth2Error | undefined

The underlying OAuth 2.0 error when exchange fails.

Error Codes

enum AccessTokenForConnectionErrorCode {
  MISSING_SESSION = "missing_session",
  MISSING_REFRESH_TOKEN = "missing_refresh_token",
  FAILED_TO_EXCHANGE = "failed_to_exchange_refresh_token"
}

Example

import { getAccessTokenForConnection } from '@auth0/nextjs-auth0/server';

try {
  const { accessToken } = await getAccessTokenForConnection({
    connection: 'google-oauth2'
  });
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    if (error.code === 'failed_to_exchange_refresh_token') {
      console.error('Failed to get connection access token');
    }
  }
}

CustomTokenExchangeError

Thrown when a custom token exchange operation fails.

Properties

code

string

required

One of: "missing_subject_token", "invalid_subject_token_type", "missing_actor_token_type", or "exchange_failed"

message

string

required

Error-specific message describing the validation failure or exchange error.

cause

OAuth2Error | undefined

The underlying OAuth 2.0 error when exchange fails.

Error Codes

enum CustomTokenExchangeErrorCode {
  MISSING_SUBJECT_TOKEN = "missing_subject_token",
  INVALID_SUBJECT_TOKEN_TYPE = "invalid_subject_token_type",
  MISSING_ACTOR_TOKEN_TYPE = "missing_actor_token_type",
  EXCHANGE_FAILED = "exchange_failed"
}

When Thrown

missing_subject_token: The subject_token is missing or empty
invalid_subject_token_type: The subject_token_type is not a valid URI, wrong length, or uses a reserved namespace
missing_actor_token_type: The actor_token was provided without actor_token_type
exchange_failed: The token exchange request failed

Example

import { customTokenExchange } from '@auth0/nextjs-auth0/server';

try {
  const result = await customTokenExchange({
    subjectToken: 'external-token',
    subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token'
  });
} catch (error) {
  if (error && typeof error === 'object' && 'code' in error) {
    switch (error.code) {
      case 'missing_subject_token':
        console.error('Subject token is required');
        break;
      case 'invalid_subject_token_type':
        console.error('Subject token type must be a valid URI');
        break;
      case 'exchange_failed':
        console.error('Token exchange failed:', error.cause?.code);
        break;
    }
  }
}

SdkError - Base error class
DPoP Errors - DPoP-specific errors
MFA Errors - Multi-factor authentication errors

Client

Server

Errors

Types

​Overview

​OAuth2Error

​Properties

​Usage

​DiscoveryError

​Properties

​When Thrown

​Example

​MissingStateError

​Properties

​When Thrown

​InvalidStateError

​Properties

​When Thrown

​Example

​InvalidConfigurationError

​Properties

​When Thrown

​Example

​AuthorizationError

​Properties

​When Thrown

​Example

​AuthorizationCodeGrantRequestError

​Properties

​When Thrown

​AuthorizationCodeGrantError

​Properties

​When Thrown

​Example

​BackchannelLogoutError

​Properties

​When Thrown

​BackchannelAuthenticationNotSupportedError

​Properties

​When Thrown

​Example

​BackchannelAuthenticationError

​Properties

​When Thrown

​AccessTokenError

​Properties

​Access Token Error Codes

​When Thrown

​Example

​AccessTokenForConnectionError

​Properties

​Error Codes

​Example

​CustomTokenExchangeError

​Properties

​Error Codes

​When Thrown

​Example

​Related

Build docs developers (and LLMs) love

Overview

OAuth2Error

Properties

Usage

DiscoveryError

Properties

When Thrown

Example

MissingStateError

Properties

When Thrown

InvalidStateError

Properties

When Thrown

Example

InvalidConfigurationError

Properties

When Thrown

Example

AuthorizationError

Properties

When Thrown

Example

AuthorizationCodeGrantRequestError

Properties

When Thrown

AuthorizationCodeGrantError

Properties

When Thrown

Example

BackchannelLogoutError

Properties

When Thrown

BackchannelAuthenticationNotSupportedError

Properties

When Thrown

Example

BackchannelAuthenticationError

Properties

When Thrown

AccessTokenError

Properties

Access Token Error Codes

When Thrown

Example

AccessTokenForConnectionError

Properties

Error Codes

Example

CustomTokenExchangeError

Properties

Error Codes

When Thrown

Example

Related