OAuth Errors

OAuth 2.0 and OpenID Connect related errors in the 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: '[e-mail]' });
} 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;
    }
  }
}

Related

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