fix(clerk-js): Prevent session cookie removal during offline token refresh

Author: bratsos

.changeset/three-ads-fold.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Fix random sign-outs when the browser temporarily loses network connectivity.

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

@@ -1,6 +1,12 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { isValidBrowserOnline } from '@clerk/shared/browser';
-import { ClerkOfflineError, ClerkWebAuthnError, is4xxError, MissingExpiredTokenError } from '@clerk/shared/error';
+import {
+  ClerkOfflineError,
+  ClerkRuntimeError,
+  ClerkWebAuthnError,
+  is4xxError,
+  MissingExpiredTokenError,
+} from '@clerk/shared/error';
 import {
   convertJSONToPublicKeyRequestOptions,
   serializePublicKeyCredentialAssertion,
@@ -435,18 +441,28 @@ export class Session extends BaseResource implements SessionResource {
     // Dispatch tokenUpdate only for __session tokens with the session's active organization ID, and not JWT templates
     const shouldDispatchTokenUpdate = !template && organizationId === this.lastActiveOrganizationId;
 
+    let result: string | null;
+
     if (cacheResult) {
       // Proactive refresh is handled by timers scheduled in the cache
       // Prefer synchronous read to avoid microtask overhead when token is already resolved
       const cachedToken = cacheResult.entry.resolvedToken ?? (await cacheResult.entry.tokenResolver);
-      if (shouldDispatchTokenUpdate) {
+      // Don't emit empty token update when offline — preserve session cookie
+      if (shouldDispatchTokenUpdate && (cachedToken.getRawString() || isValidBrowserOnline())) {
         eventBus.emit(events.TokenUpdate, { token: cachedToken });
       }
-      // Return null when raw string is empty to indicate signed-out state
-      return cachedToken.getRawString() || null;
+      result = cachedToken.getRawString() || null;
+    } else {
+      result = await this.#fetchToken(template, organizationId, tokenId, shouldDispatchTokenUpdate, skipCache);
+    }
+
+    // Throw when offline and no token so retry() in getToken() can fire.
+    // Without this, _getToken returns null (success) and retry() never calls shouldRetry.
+    if (result === null && !isValidBrowserOnline()) {
+      throw new ClerkRuntimeError('Network request failed while offline', { code: 'network_error' });
     }
 
-    return this.#fetchToken(template, organizationId, tokenId, shouldDispatchTokenUpdate, skipCache);
+    return result;
   }
 
   #createTokenResolver(
@@ -474,6 +490,12 @@ export class Session extends BaseResource implements SessionResource {
       return;
     }
 
+    // Don't dispatch empty tokens when offline — this would cause AuthCookieService
+    // to remove the session cookie even though the user is still authenticated.
+    if (!token.getRawString() && !isValidBrowserOnline()) {
+      return;
+    }
+
     eventBus.emit(events.TokenUpdate, { token });
 
     if (token.jwt) {
@@ -531,6 +553,12 @@ export class Session extends BaseResource implements SessionResource {
     // This allows concurrent calls to continue using the stale token
     tokenResolver
       .then(token => {
+        // Don't cache or dispatch empty tokens from offline failures —
+        // preserve the stale-but-valid token in cache instead.
+        if (!token.getRawString() && !isValidBrowserOnline()) {
+          return;
+        }
+
         // Cache the resolved token for future calls
         // Re-register onRefresh to handle the next refresh cycle when this token approaches expiration
         SessionTokenCache.set({

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

@@ -261,8 +261,6 @@ describe('Session', () => {
 
     describe('with offline browser and network failure', () => {
       beforeEach(() => {
-        // Use real timers for offline tests to avoid unhandled rejection issues with retry logic
-        vi.useRealTimers();
         Object.defineProperty(window.navigator, 'onLine', {
           writable: true,
           value: false,
@@ -274,10 +272,9 @@ describe('Session', () => {
           writable: true,
           value: true,
         });
-        vi.useFakeTimers();
       });
 
-      it('throws ClerkOfflineError when offline', async () => {
+      it('throws ClerkOfflineError after retries when offline', async () => {
         const session = new Session({
           status: 'active',
           id: 'session_1',
@@ -292,15 +289,15 @@ describe('Session', () => {
         mockNetworkFailedFetch();
         BaseResource.clerk = { getFapiClient: () => createFapiClient(baseFapiClientOptions) } as any;
 
-        try {
-          await session.getToken({ skipCache: true });
-          expect.fail('Expected ClerkOfflineError to be thrown');
-        } catch (error) {
-          expect(ClerkOfflineError.is(error)).toBe(true);
-        }
+        const errorPromise = session.getToken({ skipCache: true }).catch(e => e);
+
+        await vi.advanceTimersByTimeAsync(60_000);
+
+        const error = await errorPromise;
+        expect(ClerkOfflineError.is(error)).toBe(true);
       });
 
-      it('throws ClerkOfflineError after fetch fails while offline', async () => {
+      it('retries 3 times before throwing when offline', async () => {
         const session = new Session({
           status: 'active',
           id: 'session_1',
@@ -315,10 +312,39 @@ describe('Session', () => {
         mockNetworkFailedFetch();
         BaseResource.clerk = { getFapiClient: () => createFapiClient(baseFapiClientOptions) } as any;
 
-        await expect(session.getToken({ skipCache: true })).rejects.toThrow(ClerkOfflineError);
+        const errorPromise = session.getToken({ skipCache: true }).catch(e => e);
+
+        await vi.advanceTimersByTimeAsync(60_000);
+
+        await errorPromise;
 
-        // Fetch should have been called at least once
-        expect(global.fetch).toHaveBeenCalled();
+        expect(global.fetch).toHaveBeenCalledTimes(4);
+      });
+
+      it('does not emit token:update with an empty token when offline', async () => {
+        const session = new Session({
+          status: 'active',
+          id: 'session_1',
+          object: 'session',
+          user: createUser({}),
+          last_active_organization_id: null,
+          actor: null,
+          created_at: new Date().getTime(),
+          updated_at: new Date().getTime(),
+        } as SessionJSON);
+
+        mockNetworkFailedFetch();
+        BaseResource.clerk = { getFapiClient: () => createFapiClient(baseFapiClientOptions) } as any;
+
+        const errorPromise = session.getToken({ skipCache: true }).catch(e => e);
+        await vi.advanceTimersByTimeAsync(60_000);
+        await errorPromise;
+
+        const emptyTokenUpdates = dispatchSpy.mock.calls.filter(
+          (call: unknown[]) =>
+            call[0] === 'token:update' && !(call[1] as { token: { getRawString(): string } })?.token?.getRawString(),
+        );
+        expect(emptyTokenUpdates).toHaveLength(0);
       });
     });
 
@@ -588,6 +614,48 @@ describe('Session', () => {
         expect(requestSpy).not.toHaveBeenCalled();
       });
 
+      it('does not emit token:update with an empty token when background refresh fires while offline', async () => {
+        BaseResource.clerk = clerkMock();
+        const requestSpy = BaseResource.clerk.getFapiClient().request as Mock<any>;
+
+        const session = new Session({
+          status: 'active',
+          id: 'session_1',
+          object: 'session',
+          user: createUser({}),
+          last_active_organization_id: null,
+          last_active_token: { object: 'token', jwt: mockJwt },
+          actor: null,
+          created_at: new Date().getTime(),
+          updated_at: new Date().getTime(),
+        } as SessionJSON);
+
+        await Promise.resolve();
+        requestSpy.mockClear();
+        dispatchSpy.mockClear();
+
+        // Go offline before the refresh timer fires
+        Object.defineProperty(window.navigator, 'onLine', { writable: true, value: false });
+        mockNetworkFailedFetch();
+        BaseResource.clerk = { getFapiClient: () => createFapiClient(baseFapiClientOptions) } as any;
+
+        // Advance to trigger the refresh timer (~43s) and let the refresh complete
+        await vi.advanceTimersByTimeAsync(44 * 1000);
+
+        const emptyTokenUpdates = dispatchSpy.mock.calls.filter(
+          (call: unknown[]) =>
+            call[0] === 'token:update' && !(call[1] as { token: { getRawString(): string } })?.token?.getRawString(),
+        );
+        expect(emptyTokenUpdates).toHaveLength(0);
+
+        // Come back online and restore mock
+        Object.defineProperty(window.navigator, 'onLine', { writable: true, value: true });
+        BaseResource.clerk = clerkMock();
+
+        const token = await session.getToken();
+        expect(token).toEqual(mockJwt);
+      });
+
       it('does not make API call when token has plenty of time remaining', async () => {
         BaseResource.clerk = clerkMock();
         const requestSpy = BaseResource.clerk.getFapiClient().request as Mock<any>;