OAuthError

Error object and error code constants for OAuth-specific failures in the GitHub OAuth flow.

Overview

OAuthError is not a class but an object with factory functions and a type guard. All OAuth-specific errors produced by the hook are plain Error instances with a name of "OAuthError" and a code property set to one of the OAuthErrorCode constants.

Use OAuthError.isOAuthError(error) to narrow an unknown error to the OAuthError type, then inspect error.code to determine what went wrong.

Import

import { OAuthError, OAuthErrorCode } from '@react-oauth/github';

OAuthError

OAuthError is an object containing factory functions and a type guard. There is no new OAuthError() constructor.

Type definition

type OAuthError = Error & {
  code: OAuthErrorCode;
};

Every OAuthError instance is a standard Error with:

• name set to "OAuthError"
• message set to "<code> <description>" (e.g., "OA001 The Popup Closed")
• code set to one of the OAuthErrorCode values

OAuthError.isOAuthError

OAuthError.isOAuthError(error: unknown): error is OAuthError

A type guard that returns true when error is an Error instance with a valid code property matching one of the known OAuthErrorCode values. Use this before accessing error.code to avoid runtime errors when handling the onError callback.

onError: (error) => {
  if (OAuthError.isOAuthError(error)) {
    // error.code is now typed as OAuthErrorCode
    console.log(error.code);
  }
}

OAuthErrorCode

OAuthErrorCode is a const object that maps error names to their string codes. The type OAuthErrorCode is the union of all its values.

Type definition

const OAuthErrorCode = {
  POPUP_CLOSED:   'OA001',
  POPUP_BLOCKED:  'OA002',
  STATE_MISMATCH: 'OA003',
  MISSING_CODE:   'OA004',
} as const;

type OAuthErrorCode = typeof OAuthErrorCode[keyof typeof OAuthErrorCode];

Error codes

Constant	Code	Description
OAuthErrorCode.POPUP_CLOSED	OA001	The user closed the popup window before completing authentication.
OAuthErrorCode.POPUP_BLOCKED	OA002	The browser blocked the popup window. The user needs to allow popups for your site.
OAuthErrorCode.STATE_MISMATCH	OA003	The state parameter returned by GitHub does not match the original value. Possible CSRF attack.
OAuthErrorCode.MISSING_CODE	OA004	The authorization code was not present in GitHub’s redirect response.

A STATE_MISMATCH error (OA003) may indicate a CSRF attack. Do not proceed with the OAuth flow if this error occurs.

Usage example

import { useGitHubLogin, OAuthError, OAuthErrorCode } from '@react-oauth/github';

function LoginButton() {
  const { initiateGitHubLogin, isLoading } = useGitHubLogin({
    clientId: 'your-client-id',
    onSuccess: (response) => {
      sendCodeToBackend(response.code);
    },
    onError: (error) => {
      if (OAuthError.isOAuthError(error)) {
        switch (error.code) {
          case OAuthErrorCode.POPUP_CLOSED:
            // User dismissed the popup — no action needed
            console.log('User closed the login popup');
            break;

          case OAuthErrorCode.POPUP_BLOCKED:
            // Ask the user to allow popups for this site
            alert('Please allow popups for this site and try again.');
            break;

          case OAuthErrorCode.STATE_MISMATCH:
            // Possible CSRF — treat as a security issue
            console.error('CSRF state mismatch detected');
            break;

          case OAuthErrorCode.MISSING_CODE:
            // GitHub redirected back without a code
            console.error('Authorization code not found in response');
            break;

          default:
            console.error('OAuth error:', error.message);
        }
      } else {
        // Non-OAuth error (e.g., network failure)
        console.error('Unexpected error:', error);
      }
    },
  });

  return (
    <button onClick={initiateGitHubLogin} disabled={isLoading}>
      {isLoading ? 'Authenticating...' : 'Sign in with GitHub'}
    </button>
  );
}

Handling popup blocked

OA002 occurs when the browser blocks the popup. This typically happens when initiateGitHubLogin is not called directly from a user gesture (such as a click handler). Calling it inside a setTimeout, Promise, or other async callback after the user gesture may cause browsers to block the popup.

Always call initiateGitHubLogin synchronously inside a click handler to ensure the browser treats it as a user-initiated popup.