chore(clerk-js): Improve session refresh retry logic

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };
 

.changeset/chubby-lies-report.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve session refresh logic.
+- Switched from interval-based polling to timeout-based polling, ensuring retries for a `getToken()` call complete before the next poll begins.
+- `Clerk.handleUnauthenticated()` now sets the session to null when a `/client` request returns a `500` status code, preventing infinite request loops.
+- Improved error handling: If the `/client` request fails during initialization, the poller stops, a dummy client is created, a manual request to `/tokens` is attempted, and polling resumes.

.changeset/five-towns-start.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Set `retryImmediately: false` as the default for `retry()`.

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
  "files": [
  { "path": "./dist/clerk.js", "maxSize": "582.5kB" },
- { "path": "./dist/clerk.browser.js", "maxSize": "79.6kB" },
+ { "path": "./dist/clerk.browser.js", "maxSize": "79.8kB" },
  { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "96KB" },
  { "path": "./dist/vendors*.js", "maxSize": "30KB" },

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

@@ -1,6 +1,7 @@
 import { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserJWTInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError } from '@clerk/shared/error';
+import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError } from '@clerk/shared/error';
+import { noop } from '@clerk/shared/utils';
 import type { Clerk, InstanceType } from '@clerk/types';
 
 import { clerkCoreErrorTokenRefreshFailed, clerkMissingDevBrowserJwt } from '../errors';
@@ -109,11 +110,18 @@ export class AuthCookieService {
  this.devBrowser.clear();
  }
 
-private startPollingForToken() {
+public startPollingForToken() {
  if (!this.poller) {
  this.poller = new SessionCookiePoller();
+ this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
+ }
+ }
+
+ public stopPollingForToken() {
+ if (this.poller) {
+ this.poller.stopPollingForSessionToken();
+ this.poller = null;
  }
- this.poller.startPollingForSessionToken(() => this.refreshSessionToken());
  }
 
  private refreshTokenOnFocus() {
@@ -173,16 +181,18 @@ export class AuthCookieService {
  }
 
  private handleGetTokenError(e: any) {
- //throw if not a clerk error
- if (!isClerkAPIResponseError(e)) {
+ //throw if not a clerk api error (aka fapi error) and not a network error
+ if (!isClerkAPIResponseError(e) && !isClerkRuntimeError(e)) {
  clerkCoreErrorTokenRefreshFailed(e.message || e);
  }
 
  //sign user out if a 4XX error
  if (is4xxError(e)) {
- void this.clerk.handleUnauthenticated();
+ void this.clerk.handleUnauthenticated().catch(noop);
  return;
  }
+ // Treat any other error as a noop
+ // TODO(debug-logs): Once debug logs is available log this error.
  }
 
  /**

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

@@ -9,21 +9,29 @@ export class SessionCookiePoller {
  private lock = SafeLock(REFRESH_SESSION_TOKEN_LOCK_KEY);
  private workerTimers = createWorkerTimers();
  private timerId: ReturnType<typeof this.workerTimers.setInterval> | null = null;
+ // Disallows for multiple `startPollingForSessionToken()` calls before `callback` is executed.
+ private initiated = false;
 
- public startPollingForSessionToken(cb: () => unknown): void {
- if (this.timerId) {
+ public startPollingForSessionToken(cb: () => Promise<unknown>): void {
+ if (this.timerId || this.initiated) {
  return;
  }
 
- this.timerId = this.workerTimers.setInterval(() => {
- void this.lock.acquireLockAndRun(cb);
- }, INTERVAL_IN_MS);
+ const run = async () => {
+ this.initiated = true;
+ await this.lock.acquireLockAndRun(cb);
+ this.timerId = this.workerTimers.setTimeout(run, INTERVAL_IN_MS);
+ };
+
+ void run();
  }
 
  public stopPollingForSessionToken(): void {
- if (this.timerId) {
- this.workerTimers.clearInterval(this.timerId);
+ // Note: `timerId` can be 0.
+ if (this.timerId != null) {
+ this.workerTimers.clearTimeout(this.timerId);
  this.timerId = null;
  }
+ this.initiated = false;
  }
 }

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

@@ -9,7 +9,7 @@ export function SafeLock(key: string) {
  await lock.releaseLock(key);
  });
 
- const acquireLockAndRun = async (cb: () => unknown) => {
+ const acquireLockAndRun = async (cb: () => Promise<unknown>) => {
  if ('locks' in navigator && isSecureContext) {
  const controller = new AbortController();
  const lockTimeout = setTimeout(() => controller.abort(), 4999);

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

@@ -1745,8 +1745,11 @@ export class Clerk implements ClerkInterface {
  }
  return this.setActive({ session: null });
  } catch (err) {
- // Handle the 403 Forbidden
- if (err.status === 403) {
+ // `/client` can fail with either a 401, a 403, 500 or network errors.
+ // 401 is already handled internally in our fetcher.
+ // 403 means that the client is blocked, signing out the user is the only option.
+ // 500 means that the client is not working, signing out the user is the only option, since the intention was to sign out the user.
+ if (isClerkAPIResponseError(err) && [403, 500].includes(err.status)) {
  return this.setActive({ session: null });
  } else {
  throw err;
@@ -2148,8 +2151,20 @@ export class Clerk implements ClerkInterface {
 
  this.updateClient(localClient);
 
- // Always grab a fresh token
- await this.session?.getToken({ skipCache: true });
+ /**
+ * 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();
+ });
 
  // 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

@@ -232,17 +232,20 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response =
- // retry only on GET requests for safety
- overwrittenRequestMethod === 'GET'
- ? await retry(() => fetch(urlStr, fetchOpts), {
- initialDelay: 500,
- maxDelayBetweenRetries: 3000,
- shouldRetry: (_: unknown, iterationsCount: number) => {
- return iterationsCount < maxTries;
- },
- })
- : await fetch(urlStr, fetchOpts);
+ response = await retry(() => fetch(urlStr, fetchOpts), {
+ // This retry handles only network errors, not 4xx or 5xx responses,
+ // so we want to try once immediately to handle simple network blips.
+ // Since fapiClient is responsible for the network layer only,
+ // callers need to use their own retry logic where needed.
+ retryImmediately: true,
+ // And then exponentially back off with a max delay of 5 seconds.
+ 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;
+ },
+ });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }

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

@@ -92,8 +92,17 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
+ // This will retry the getToken call if it fails with a non-4xx error
+ // We're going to trigger 8 retries in the span of ~3 minutes,
+ // Example delays: 3s, 5s, 13s, 19s, 26s, 34s, 43s, 50s, total: ~193s
  return retry(() => this._getToken(options), {
- shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
+ factor: 1.55,
+ initialDelay: 3 * 1000,
+ maxDelayBetweenRetries: 50 * 1_000,
+ jitter: false,
+ shouldRetry: (error, iterationsCount) => {
+ return !is4xxError(error) && iterationsCount <= 8;
+ },
  });
  };
 

packages/shared/src/retry.ts

@@ -29,7 +29,7 @@ type RetryOptions = Partial<{
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
- * @default true
+ * @default false
  */
  retryImmediately: boolean;
  /**
@@ -44,7 +44,7 @@ const defaultOptions: Required<RetryOptions> = {
  maxDelayBetweenRetries: 0,
  factor: 2,
  shouldRetry: (_: unknown, iteration: number) => iteration < 5,
- retryImmediately: true,
+ retryImmediately: false,
  jitter: true,
 };