fix(clerk-js): fail fast when the origin is slow at load (#9065)

Author: nikosdouvlis

.changeset/clerkjs-fail-fast-slow-origin.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Fail fast when the Clerk Frontend API (FAPI) is slow or unreachable during load. The client request and the load-recovery token mint are now bounded by a timeout, and the timed-out client request is aborted instead of being left in flight. A cold `Clerk.load()` renders identity from a freshly minted session token (falling back to the session cookie if the mint fails) in seconds instead of hanging while retries run. After a degraded load, the client is re-fetched in the background without a time limit, so a slow-but-healthy origin recovers full client data (user profile, other sessions) without a reload. Also fixes hooks like `useUser()` keeping the cookie-derived stub user after full user data arrives. Adds a `timeLimit` utility to `@clerk/shared/utils` that optionally aborts an `AbortController` on timeout.

AGENTS.md

@@ -9,6 +9,7 @@ Clerk's JavaScript SDK and library monorepo.
 - Use `pnpm` only. `npm` and `yarn` are blocked by `preinstall`. Node `>=24.15`, pnpm `>=10.33`.
 - Every PR needs a changeset. `pnpm changeset` for package changes, `pnpm changeset:empty` for tooling/repo-only. Empty changesets are two `---` delimiters with no body. A changeset is a changelog entry for users upgrading the package, not a summary of the work done in the PR. Describe the user-facing change (what changed for someone consuming the library and how it affects them) rather than the implementation details of the diff. If a change has no user-facing impact, use an empty changeset.
 - Commits must be conventional: `type(scope):` (commitlint enforces, on the PR title). `scope` is the package name without `@clerk/`, or `repo` / `release` / `e2e` / `ci` / `*`. `clerk-js` uses scope `js` (`clerk-js` is also accepted). Scope is mandatory; `docs` is a type, not a scope.
+- Keep code comments minimal. Do not add a comment unless it is critical to explain WHY a non-obvious change was made; never restate what the code does. When one is warranted, keep it to a single terse line, not a verbose multi-line block.
 
 ## References
 

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

@@ -8,6 +8,7 @@ import type {
   SignUpJSON,
   TokenResource,
 } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
 import { waitFor } from '@testing-library/react';
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, test, vi } from 'vitest';
 
@@ -26,6 +27,9 @@ const mockEnvironmentFetch = vi.fn(() => Promise.resolve({}));
 vi.mock('../resources/Client');
 vi.mock('../resources/Environment');
 
+const { mockCreateClientFromJwt } = vi.hoisted(() => ({ mockCreateClientFromJwt: vi.fn() }));
+vi.mock('../jwt-client', () => ({ createClientFromJwt: mockCreateClientFromJwt }));
+
 vi.mock('../auth/devBrowser', () => ({
   createDevBrowser: (): DevBrowser => ({
     clear: vi.fn(),
@@ -818,6 +822,176 @@ describe('Clerk singleton', () => {
         });
       },
     );
+
+    describe('when the client fetch fails or hangs at load', () => {
+      let startPollSpy: ReturnType<typeof vi.spyOn>;
+      let stopPollSpy: ReturnType<typeof vi.spyOn>;
+      let callLog: string[];
+
+      const sessionClient = (session: any) => ({
+        signedInSessions: [session],
+        lastActiveSessionId: session.id,
+      });
+      const makeSession = (overrides: Record<string, unknown> = {}) => ({
+        id: 'sess_1',
+        status: 'active',
+        user: {},
+        getToken: vi.fn(() => Promise.resolve('fresh-token')),
+        clearCache: vi.fn(),
+        ...overrides,
+      });
+
+      // `load()` awaits native crypto (cookie suffix) before scheduling the timeout, so a single
+      // advance can run before the timer exists; advance the budget repeatedly until load settles.
+      const pumpUntilSettled = async (promise: Promise<unknown>) => {
+        let settled = false;
+        const tracked = promise.then(
+          v => ((settled = true), v),
+          e => ((settled = true), Promise.reject(e)),
+        );
+        for (let i = 0; i < 20 && !settled; i++) {
+          await vi.advanceTimersByTimeAsync(5000);
+        }
+        await tracked;
+      };
+
+      beforeEach(async () => {
+        callLog = [];
+        // Import at runtime (not top-level) so this module does not reorder the
+        // static graph and break the auto-mocked Environment/Client resources.
+        const { AuthCookieService } = await import('../auth/AuthCookieService');
+        startPollSpy = vi
+          .spyOn(AuthCookieService.prototype, 'startPollingForToken')
+          .mockImplementation(() => void callLog.push('startPoll'));
+        stopPollSpy = vi
+          .spyOn(AuthCookieService.prototype, 'stopPollingForToken')
+          .mockImplementation(() => void callLog.push('stopPoll'));
+        mockClientFetch.mockClear();
+        mockCreateClientFromJwt.mockReturnValue({ signedInSessions: [], lastActiveSessionId: null });
+      });
+
+      afterEach(() => {
+        startPollSpy.mockRestore();
+        stopPollSpy.mockRestore();
+        mockCreateClientFromJwt.mockReset();
+        vi.useRealTimers();
+      });
+
+      it('fails fast and marks Clerk degraded when the client fetch hangs', async () => {
+        vi.useFakeTimers();
+        // Only the primary fetch hangs; the background retry must resolve so it can't stall the test.
+        mockClientFetch
+          .mockReturnValueOnce(new Promise(() => {}))
+          .mockResolvedValue({ signedInSessions: [], lastActiveSessionId: null });
+
+        const sut = new Clerk(productionPublishableKey);
+        await pumpUntilSettled(sut.load());
+
+        expect(sut.status).toBe('degraded');
+        expect(stopPollSpy).toHaveBeenCalled();
+        expect(startPollSpy).toHaveBeenCalled();
+        expect(mockClientFetch.mock.calls[0]?.[0]?.abortSignal?.aborted).toBe(true);
+      });
+
+      it('builds the degraded identity from the minted token and falls back to the cookie only if the mint fails', async () => {
+        const stubSession = makeSession();
+        const freshSession = { id: 'sess_1', status: 'active', user: { id: 'user_fresh' } };
+        const freshClient = { signedInSessions: [freshSession], lastActiveSessionId: 'sess_1' };
+        mockClientFetch.mockRejectedValue(new Error('client fetch failed'));
+        mockCreateClientFromJwt.mockReturnValueOnce(sessionClient(stubSession)).mockReturnValueOnce(freshClient);
+
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load();
+
+        expect(mockCreateClientFromJwt).toHaveBeenCalledTimes(2);
+        expect(mockCreateClientFromJwt).toHaveBeenNthCalledWith(2, 'fresh-token');
+        expect(sut.client).toBe(freshClient);
+        expect(sut.session).toBe(freshSession);
+        expect(sut.status).toBe('degraded');
+      });
+
+      it('clears the token cache and mints without skipCache when the client fetch fails with a session present', async () => {
+        const getToken = vi.fn(() => {
+          callLog.push('getToken');
+          return Promise.resolve('fresh-token');
+        });
+        const clearCache = vi.fn(() => void callLog.push('clearCache'));
+        const session = makeSession({ getToken, clearCache });
+        mockClientFetch.mockRejectedValue(new Error('client fetch failed'));
+        mockCreateClientFromJwt.mockReturnValue(sessionClient(session));
+
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load();
+
+        expect(getToken).toHaveBeenCalledWith();
+        expect(getToken).not.toHaveBeenCalledWith({ skipCache: true });
+        expect(callLog).toEqual(['startPoll', 'stopPoll', 'clearCache', 'getToken', 'startPoll']);
+        expect(sut.status).toBe('degraded');
+      });
+
+      it('re-clears the token cache before restarting the poller when the recovery mint hangs', async () => {
+        vi.useFakeTimers();
+        const getToken = vi.fn(() => {
+          callLog.push('getToken');
+          return new Promise<string>(() => {});
+        });
+        const clearCache = vi.fn(() => void callLog.push('clearCache'));
+        const session = makeSession({ getToken, clearCache });
+        mockClientFetch.mockRejectedValue(new Error('client fetch failed'));
+        mockCreateClientFromJwt.mockReturnValue(sessionClient(session));
+
+        const sut = new Clerk(productionPublishableKey);
+        await pumpUntilSettled(sut.load());
+
+        expect(callLog).toEqual(['startPoll', 'stopPoll', 'clearCache', 'getToken', 'clearCache', 'startPoll']);
+        expect(sut.status).toBe('degraded');
+      });
+
+      it('renders the empty client without minting when there is no session cookie', async () => {
+        mockClientFetch.mockRejectedValue(new Error('client fetch failed'));
+
+        const sut = new Clerk(productionPublishableKey);
+        await sut.load();
+
+        expect(sut.session).toBeNull();
+        expect(callLog).toEqual(['startPoll', 'stopPoll', 'startPoll']);
+        expect(sut.status).toBe('degraded');
+      });
+
+      it('rethrows a 4xx client error without entering the mint path', async () => {
+        const err = Object.assign(new Error('bad request'), { status: 400 });
+        mockClientFetch.mockRejectedValue(err);
+
+        const sut = new Clerk(productionPublishableKey);
+        await expect(sut.load()).rejects.toBe(err);
+
+        expect(mockCreateClientFromJwt).not.toHaveBeenCalled();
+      });
+
+      it('re-fetches /client in the background after a degraded load and applies the late response', async () => {
+        vi.useFakeTimers();
+        const stubSession = makeSession();
+        const realSession = { id: 'sess_1', status: 'active', user: { id: 'user_real' } };
+        const realClient = { id: 'client_real', signedInSessions: [realSession], lastActiveSessionId: 'sess_1' };
+        const refetch = createDeferredPromise();
+        mockClientFetch.mockRejectedValueOnce(new Error('client fetch failed')).mockReturnValueOnce(refetch.promise);
+        mockCreateClientFromJwt.mockReturnValue(sessionClient(stubSession));
+
+        const sut = new Clerk(productionPublishableKey);
+        await pumpUntilSettled(sut.load());
+
+        expect(sut.status).toBe('degraded');
+        expect(mockClientFetch).toHaveBeenCalledTimes(2);
+
+        // The background retry is not bounded by INITIALIZATION_TIMEOUT_MS.
+        await vi.advanceTimersByTimeAsync(60_000);
+        refetch.resolve(realClient);
+        await vi.advanceTimersByTimeAsync(0);
+
+        expect(sut.client).toBe(realClient);
+        expect(sut.session).toBe(realSession);
+      });
+    });
   });
 
   describe('updateSessionCookie monotonic backstop', () => {

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import { mockJwt } from '@/test/core-fixtures';
+
+import { createClientFromJwt } from '../jwt-client';
+
+describe('createClientFromJwt', () => {
+  it('creates a client with a session and user derived from the JWT claims', () => {
+    const client = createClientFromJwt(mockJwt);
+
+    expect(client.lastActiveSessionId).toBe('sess_2GbDB4enNdCa5vS1zpC3Xzg9tK9');
+    expect(client.signedInSessions[0]?.id).toBe('sess_2GbDB4enNdCa5vS1zpC3Xzg9tK9');
+    expect(client.signedInSessions[0]?.user?.id).toBe('user_2GIpXOEpVyJw51rkZn9Kmnc6Sxr');
+  });
+
+  it('stamps the stub user with an ancient updatedAt so the real user always replaces it in memoized listeners', () => {
+    const client = createClientFromJwt(mockJwt);
+
+    expect(client.signedInSessions[0]?.user?.updatedAt?.getTime()).toBe(1);
+  });
+
+  it('returns an empty client when the JWT is missing', () => {
+    const client = createClientFromJwt(undefined);
+
+    expect(client.signedInSessions).toEqual([]);
+    expect(client.lastActiveSessionId).toBeNull();
+  });
+});

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

@@ -140,7 +140,7 @@ import type {
 } from '@clerk/shared/types';
 import type { ClerkUI } from '@clerk/shared/ui';
 import { addClerkPrefix, isAbsoluteUrl, stripScheme } from '@clerk/shared/url';
-import { allSettled, handleValueOrFn, noop } from '@clerk/shared/utils';
+import { allSettled, handleValueOrFn, noop, timeLimit } from '@clerk/shared/utils';
 import type { QueryClient } from '@tanstack/query-core';
 
 import { debugLogger, initDebugLogger } from '@/utils/debug';
@@ -215,6 +215,7 @@ const CANNOT_RENDER_API_KEYS_ORG_DISABLED_ERROR_CODE = 'cannot_render_api_keys_o
 const CANNOT_RENDER_SELF_SERVE_SSO_DISABLED_ERROR_CODE = 'cannot_render_self_serve_sso_disabled';
 const CANNOT_RENDER_CONFIGURE_SSO_EMAIL_ADDRESS_DISABLED_ERROR_CODE =
   'cannot_render_configure_sso_email_address_disabled';
+const INITIALIZATION_TIMEOUT_MS = 7_000;
 const defaultOptions: ClerkOptions = {
   polling: true,
   standardBrowser: true,
@@ -3245,8 +3246,13 @@ export class Clerk implements ClerkInterface {
           });
 
         const initClient = async () => {
-          return Client.getOrCreateInstance()
-            .fetch()
+          // Abort the /client request on timeout so clerkjs loading does not hang
+          const clientFetchController = new AbortController();
+          return timeLimit(
+            Client.getOrCreateInstance().fetch({ abortSignal: clientFetchController.signal }),
+            INITIALIZATION_TIMEOUT_MS,
+            clientFetchController,
+          )
             .then(res => this.updateClient(res))
             .catch(async e => {
               /**
@@ -3259,27 +3265,32 @@ export class Clerk implements ClerkInterface {
 
               ++initializationDegradedCounter;
 
-              const jwtInCookie = this.#authService?.getSessionCookie();
-              const localClient = createClientFromJwt(jwtInCookie);
-
-              this.updateClient(localClient);
-
               /**
                * In most scenarios we want the poller to stop while we are fetching a fresh token during an outage.
                * We want to avoid having the below `getToken()` retrying at the same time as the poller.
                */
               this.#authService?.stopPollingForToken();
 
-              // Attempt to grab a fresh token
-              await this.session
-                ?.getToken({ skipCache: true })
-                // If the token fetch fails, let Clerk be marked as loaded and leave it up to the poller.
-                .catch(() => null)
-                .finally(() => {
-                  this.#authService?.startPollingForToken();
-                });
+              try {
+                const session = this.#defaultSession(createClientFromJwt(this.#authService?.getSessionCookie()));
+                // Prefer minting a fresh token as its claims are fresher than the cookie's
+                session?.clearCache();
+                const jwt = session
+                  ? await timeLimit(session.getToken(), INITIALIZATION_TIMEOUT_MS).catch(() => {
+                      session.clearCache();
+                      return this.#authService?.getSessionCookie();
+                    })
+                  : this.#authService?.getSessionCookie();
+                this.updateClient(createClientFromJwt(jwt));
+              } finally {
+                this.#authService?.startPollingForToken();
+              }
+
+              void Client.getOrCreateInstance()
+                .fetch()
+                .then(res => this.updateClient(res))
+                .catch(noop);
 
-              // Allows for Clerk to be marked as loaded with the client and session created from the JWT.
               return null;
             });
         };

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

@@ -257,8 +257,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
           initialDelay: 700,
           maxDelayBetweenRetries: 5000,
           shouldRetry: (_: unknown, iterations: number) => {
-            // We want to retry only GET requests, as other methods are not idempotent.
-            return overwrittenRequestMethod === 'GET' && iterations < maxTries;
+            // We want to retry only GET requests, as other methods are not idempotent,
+            // and stop as soon as the caller aborted the request.
+            return overwrittenRequestMethod === 'GET' && iterations < maxTries && !fetchOpts.signal?.aborted;
           },
           onBeforeRetry: (iteration: number): void => {
             // Add the retry attempt to the query string params.

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

@@ -71,6 +71,10 @@ export function createClientFromJwt(jwt: string | undefined | null): Client {
         user: {
           object: 'user',
           id: userId,
+          // Epoch 1, not 0: unixEpochToDate treats 0 as "now", and a "now" timestamp makes
+          // memoizeListenerCallback consider this stub newer than the real user fetched later,
+          // so listeners would keep rendering the stub after the full client arrives.
+          updated_at: 1,
           organization_memberships:
             orgId && orgSlug && orgRole
               ? [

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

@@ -19,6 +19,7 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
   forceUpdateClient?: boolean;
   skipUpdateClient?: boolean;
   fetchMaxTries?: number;
+  abortSignal?: AbortSignal;
 };
 
 export type BaseMutateParams = {
@@ -207,6 +208,7 @@ export abstract class BaseResource {
         method: 'GET',
         path: this.path(),
         rotatingTokenNonce: opts.rotatingTokenNonce,
+        signal: opts.abortSignal,
       },
       opts,
     );

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

@@ -73,8 +73,8 @@ export class Client extends BaseResource implements ClientResource {
     return this._basePut();
   }
 
-  fetch({ fetchMaxTries }: { fetchMaxTries?: number } = {}): Promise<this> {
-    return this._baseGet({ fetchMaxTries });
+  fetch({ fetchMaxTries, abortSignal }: { fetchMaxTries?: number; abortSignal?: AbortSignal } = {}): Promise<this> {
+    return this._baseGet({ fetchMaxTries, abortSignal });
   }
 
   async destroy(): Promise<void> {