fix(clerk-js): Correct init retry logic

Author: jacekradko

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -1,4 +1,4 @@
-import { EmailLinkErrorCodeStatus } from '@clerk/shared/error';
+import { ClerkRuntimeError, EmailLinkErrorCodeStatus } from '@clerk/shared/error';
 import type {
   ActiveSessionResource,
   PendingSessionResource,
@@ -13,8 +13,10 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, test,
 import { mockJwt } from '@/test/core-fixtures';
 
 import { mockNativeRuntime } from '../../test/utils';
+import { AuthCookieService } from '../auth/AuthCookieService';
 import type { DevBrowser } from '../auth/devBrowser';
 import { Clerk } from '../clerk';
+import * as errorsModule from '../errors';
 import { eventBus, events } from '../events';
 import type { DisplayConfig, Organization } from '../resources/internal';
 import { BaseResource, Client, Environment, SignIn, SignUp } from '../resources/internal';
@@ -157,6 +159,118 @@ describe('Clerk singleton', () => {
     });
   });
 
+  describe('load retry behavior', () => {
+    let originalMountComponentRenderer: typeof Clerk.mountComponentRenderer;
+
+    const createMockAuthService = () => ({
+      decorateUrlWithDevBrowserToken: vi.fn((url: URL) => url),
+      getSessionCookie: vi.fn(() => null),
+      handleUnauthenticatedDevBrowser: vi.fn(() => Promise.resolve()),
+      isSignedOut: vi.fn(() => false),
+      setClientUatCookieForDevelopmentInstances: vi.fn(),
+      startPollingForToken: vi.fn(),
+      stopPollingForToken: vi.fn(),
+    });
+
+    const createMockComponentControls = () => {
+      const componentInstance = {
+        mountImpersonationFab: vi.fn(),
+        updateProps: vi.fn(),
+      };
+
+      return {
+        ensureMounted: vi.fn().mockResolvedValue(componentInstance),
+        prioritizedOn: vi.fn(),
+      };
+    };
+
+    beforeEach(() => {
+      originalMountComponentRenderer = Clerk.mountComponentRenderer;
+    });
+
+    afterEach(() => {
+      Clerk.mountComponentRenderer = originalMountComponentRenderer;
+      vi.useRealTimers();
+    });
+
+    it('retries once when dev browser authentication is lost', async () => {
+      vi.useFakeTimers();
+
+      const mockAuthService = createMockAuthService();
+      const authCreateSpy = vi
+        .spyOn(AuthCookieService, 'create')
+        .mockResolvedValue(mockAuthService as unknown as AuthCookieService);
+
+      const componentControls = createMockComponentControls();
+      const devBrowserError = Object.assign(new Error('dev browser unauthenticated'), {
+        errors: [{ code: 'dev_browser_unauthenticated' }],
+        status: 401,
+      });
+
+      const mountSpy = vi
+        .fn<NonNullable<typeof Clerk.mountComponentRenderer>>()
+        .mockImplementationOnce(() => {
+          throw devBrowserError;
+        })
+        .mockReturnValue(componentControls);
+
+      Clerk.mountComponentRenderer = mountSpy;
+      mockClientFetch.mockClear();
+
+      const sut = new Clerk(productionPublishableKey);
+
+      try {
+        const loadPromise = sut.load();
+
+        await vi.advanceTimersByTimeAsync(2000);
+        await loadPromise;
+      } finally {
+        authCreateSpy.mockRestore();
+      }
+
+      expect(mountSpy).toHaveBeenCalledTimes(2);
+      expect(mockAuthService.handleUnauthenticatedDevBrowser).toHaveBeenCalledTimes(1);
+      expect(mockClientFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('surfaces network errors after exhausting retries', async () => {
+      vi.useFakeTimers();
+
+      const mockAuthService = createMockAuthService();
+      const authCreateSpy = vi
+        .spyOn(AuthCookieService, 'create')
+        .mockResolvedValue(mockAuthService as unknown as AuthCookieService);
+
+      const networkError = new ClerkRuntimeError('Network failure', { code: 'network_error' });
+      const mountSpy = vi.fn<NonNullable<typeof Clerk.mountComponentRenderer>>().mockImplementation(() => {
+        throw networkError;
+      });
+
+      Clerk.mountComponentRenderer = mountSpy;
+      mockClientFetch.mockClear();
+
+      const errorSpy = vi.spyOn(errorsModule, 'clerkErrorInitFailed');
+      const sut = new Clerk(productionPublishableKey);
+
+      try {
+        const loadPromise = sut.load();
+        const expectationPromise = expect(loadPromise).rejects.toThrow(/Clerk: Network failure/);
+
+        await vi.advanceTimersByTimeAsync(2000);
+        await expectationPromise;
+
+        expect(mountSpy).toHaveBeenCalledTimes(2);
+        expect(mockClientFetch).toHaveBeenCalledTimes(2);
+        expect(errorSpy).toHaveBeenCalledTimes(1);
+        expect(errorSpy).toHaveBeenLastCalledWith(networkError);
+        expect(mockAuthService.handleUnauthenticatedDevBrowser).not.toHaveBeenCalled();
+      } finally {
+        authCreateSpy.mockRestore();
+        errorSpy.mockRestore();
+      }
+    });
+  });
+
   describe('.setActive', () => {
     describe('with `active` session status', () => {
       const mockSession = {

packages/clerk-js/src/core/clerk.ts

@@ -2570,10 +2570,11 @@ export class Clerk implements ClerkInterface {
 
     let initializationDegradedCounter = 0;
 
-    let retries = 0;
-    while (retries < 2) {
-      retries++;
+    const wait = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms));
 
+    const maxRetries = 2;
+    let retries = 0;
+    while (retries < maxRetries) {
       try {
         const initEnvironmentPromise = Environment.getInstance()
           .fetch({ touch: shouldTouchEnv })
@@ -2663,18 +2664,29 @@ export class Clerk implements ClerkInterface {
 
         break;
       } catch (err) {
-        if (isError(err, 'dev_browser_unauthenticated')) {
-          await this.#authService.handleUnauthenticatedDevBrowser();
-        } else if (!isValidBrowserOnline()) {
+        if (!isValidBrowserOnline()) {
           console.warn(err);
           return;
-        } else {
+        }
+
+        const isDevBrowserUnauthenticated = isError(err, 'dev_browser_unauthenticated');
+        const isNetworkError = isClerkRuntimeError(err) && err.code === 'network_error';
+
+        if (!isDevBrowserUnauthenticated && !isNetworkError) {
           throw err;
         }
-      }
 
-      if (retries >= 2) {
-        clerkErrorInitFailed();
+        retries += 1;
+
+        if (isDevBrowserUnauthenticated) {
+          await this.#authService.handleUnauthenticatedDevBrowser();
+        }
+
+        if (retries >= maxRetries) {
+          clerkErrorInitFailed(err);
+        }
+
+        await wait(Math.pow(2, retries) * 1_000);
       }
     }
 

packages/clerk-js/src/core/errors.ts

@@ -16,8 +16,46 @@ export function clerkNetworkError(url: string, e: Error): never {
   throw new Error(`${errorPrefix} Network error at "${url}" - ${e}. Please try again.`);
 }
 
-export function clerkErrorInitFailed(): never {
-  throw new Error(`${errorPrefix} Something went wrong initializing Clerk.`);
+const formatErrorCause = (cause: unknown): string | null => {
+  if (!cause) {
+    return null;
+  }
+
+  if (cause instanceof Error) {
+    return cause.message;
+  }
+
+  if (typeof cause === 'string') {
+    return cause;
+  }
+
+  if (typeof cause === 'number' || typeof cause === 'bigint' || typeof cause === 'boolean') {
+    return cause.toString();
+  }
+
+  if (typeof cause === 'symbol') {
+    return cause.description ? `Symbol(${cause.description})` : 'Symbol()';
+  }
+
+  if (typeof cause === 'function') {
+    return cause.name ? `[Function ${cause.name}]` : '[Function anonymous]';
+  }
+
+  if (typeof cause === 'object') {
+    try {
+      return JSON.stringify(cause);
+    } catch {
+      return Object.prototype.toString.call(cause);
+    }
+  }
+
+  return '[Unknown cause]';
+};
+
+export function clerkErrorInitFailed(error?: unknown): never {
+  const formattedCause = formatErrorCause(error);
+  const cause = formattedCause ? ` Cause: ${formattedCause}` : '';
+  throw new Error(`${errorPrefix} Something went wrong initializing Clerk.${cause}`);
 }
 
 export function clerkErrorDevInitFailed(msg = ''): never {