fix(clerk-js): Fix token cache refresh timer leak by jacekradko · Pull Request #8098 · clerk/javascript

jacekradko · 2026-03-17T16:43:07Z

Summary

Fix orphaned refresh timer accumulation in SessionTokenCache that caused token refresh requests to fire much earlier than expected
When set() is called multiple times for the same cache key (from _updateClient hydration AND #refreshTokenInBackground), old timers were never cleared — each leaked timer independently fired onRefresh, accelerating the effective polling rate
The fix clears existing timers at the start of setInternal before creating the new cache entry
Particularly visible after session.touch() or any API response that triggers _updateClient

Test plan

8 new unit tests covering timer cleanup on overwrite scenarios
All 45 unit tests pass
Integration test verifying stable refresh rate after session.touch()
Manual verification: sign in, trigger touch, observe network tab for ~2 minutes — token requests should maintain ~43s intervals (not accelerating)

Summary by CodeRabbit

Bug Fixes
- Fixed a proactive token refresh timer leak that could cause growing token refresh requests after session activity or switching, preventing orphaned/stale timers and reducing redundant network calls.
Tests
- Added unit and integration tests validating timers are cleaned up across repeated session updates so token refreshes remain stable and non-duplicative.

When set() was called multiple times for the same cache key, old refresh and expiration timers were never cancelled. This caused orphaned timers to accumulate — each independently firing onRefresh — making the poller appear erratic with accelerating token refresh requests. The root cause: both _updateClient (via Session constructor → #hydrateCache) and #refreshTokenInBackground call set() for the same key during a single refresh cycle. Each set() created new timers without clearing the old ones. After N cycles, N orphaned timers all fire at different offsets. Fix: clear existing timers at the start of setInternal before creating the new cache entry.

changeset-bot · 2026-03-17T16:43:13Z

🦋 Changeset detected

Latest commit: c0f0f3d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-03-17T16:43:15Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 18, 2026 6:40pm

pkg-pr-new · 2026-03-17T16:45:36Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8098

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8098

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8098

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8098

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8098

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8098

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8098

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8098

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8098

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8098

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8098

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8098

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8098

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8098

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8098

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8098

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8098

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8098

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8098

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8098

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8098

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8098

commit: c0f0f3d

coderabbitai · 2026-03-17T16:50:28Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2ff59aca-7231-4a29-8859-789ed1ed4887

📥 Commits

Reviewing files that changed from the base of the PR and between 1c01b01 and c0f0f3d.

📒 Files selected for processing (1)

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

📝 Walkthrough

Walkthrough

Clears prior refresh and expiration timers before updating entries in MemoryTokenCache.setInternal and prevents installing timers for entries overwritten while a pending tokenResolver resolves, fixing a token cache refresh timer leak. Adds unit tests under packages/clerk-js/src/core/__tests__/tokenCache.test.ts, a Playwright integration test at integration/tests/session-token-cache/refresh-timer-cleanup.test.ts, and a changeset entry for a patch release.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(clerk-js): Fix token cache refresh timer leak' directly and clearly summarizes the main change: fixing a token cache refresh timer leak in clerk-js.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📝 Coding Plan

Generate coding plan for human review comments

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/clerk-js/src/core/tokenCache.ts`:
- Around line 353-364: The cache set flow currently only clears timers on
existing entries but doesn't prevent a pending tokenResolver promise from later
installing orphaned refresh timers or invoking onRefresh after the key has been
overwritten; update the logic in the tokenCache set/update paths (the code that
constructs/assigns entries with tokenResolver, timeoutId, refreshTimeoutId and
that installs refresh timers and calls onRefresh) to attach a unique
marker/version id to each cache entry (e.g., entry.version or entry.resolverId)
when creating it and, before installing any timers or invoking onRefresh inside
tokenResolver.then/Promise continuations, verify the stored marker still matches
the current cache entry for that key—if it does not match, bail out and do not
set refreshTimeoutId or call onRefresh; apply the same guard wherever
tokenResolver continuations create timers (the other block that handles
refreshTimeoutId) so pending resolvers cannot schedule orphaned refreshes after
an overwrite.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9af73399-f0a6-4ae4-810d-636541e51793

📥 Commits

Reviewing files that changed from the base of the PR and between b9cb6e5 and fd6d143.

📒 Files selected for processing (4)

.changeset/fix-token-cache-timer-leak.md
integration/tests/session-token-cache/refresh-timer-cleanup.test.ts
packages/clerk-js/src/core/__tests__/tokenCache.test.ts
packages/clerk-js/src/core/tokenCache.ts

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

jacekradko added 2 commits March 17, 2026 11:42

chore: shorten changeset

fd6d143

github-actions bot added clerk-js integration labels Mar 17, 2026

vercel bot deployed to Preview March 17, 2026 16:43 View deployment

fix: prettier formatting

2dbdc83

coderabbitai bot reviewed Mar 17, 2026

View reviewed changes

packages/clerk-js/src/core/tokenCache.ts Show resolved Hide resolved

fix(clerk-js): add staleness guard for pending tokenResolver promises

a0d8003

vercel bot deployed to Preview March 17, 2026 16:54 View deployment

fix(e2e): reduce integration test timeout for CI

317a35e

vercel bot deployed to Preview March 17, 2026 17:15 View deployment

fix(e2e): increase test timeout to 120s for refresh timer test

1c01b01

vercel bot deployed to Preview March 17, 2026 17:56 View deployment

Merge branch 'main' into jacek/fix-token-cache-timer-leak

e40c60f

vercel bot deployed to Preview March 17, 2026 18:10 View deployment

Merge branch 'main' into jacek/fix-token-cache-timer-leak

c0f0f3d

vercel bot deployed to Preview March 18, 2026 18:40 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(clerk-js): Fix token cache refresh timer leak#8098

fix(clerk-js): Fix token cache refresh timer leak#8098
jacekradko wants to merge 8 commits intomainfrom
jacek/fix-token-cache-timer-leak

jacekradko commented Mar 17, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 17, 2026 •

edited

Loading

Reviews paused

Walkthrough

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jacekradko commented Mar 17, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jacekradko commented Mar 17, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Mar 17, 2026 •

edited

Loading

vercel bot commented Mar 17, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 17, 2026 •

edited

Loading

coderabbitai bot commented Mar 17, 2026 •

edited

Loading