feat(backend, clerk-js): Support origin outage mode

[bratsos]

Description

Checklist

• [x] pnpm test runs as expected.
• [x] pnpm build runs as expected.
• [ ] (If applicable) JSDoc comments have been added or updated for any package exports
• [ ] (If applicable) Documentation has been updated

Type of change

• [ ] 🐛 Bug fix
• [ ] 🌟 New feature
• [ ] 🔨 Breaking change
• [ ] 📖 Refactoring / dependency upgrade / documentation
• [ ] other:

Summary by CodeRabbit

• New Features

  • Added origin outage mode support for improved reliability during token expiration scenarios, enabling automatic retry with last active token when applicable.

• Tests

  • Added comprehensive test coverage for origin outage fallback behavior and token retry logic.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 8b2a3dcc37b596de44f096241777b8a5768219e3

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

This PR includes changesets to release 13 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/backend	Minor
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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[bot]]

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Dec 19, 2025 6:38pm

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Adds a new MissingExpiredTokenError class and exports it; changes Token.create to accept a search/search-parameters object and always pass body and search to fetch; updates Session to use lastActiveToken and retry with expired_token on 422 missing_expired_token errors; adds Session: '__session' query constant; updates HandshakeService to append the Session query parameter when authenticateContext.sessionToken exists; adds tests and a changeset.

Pre-merge checks

✅ 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 clearly and concisely summarizes the main feature being added: support for origin outage mode functionality across backend and clerk-js packages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

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

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 83ba39161402f18f3bae7dc223d6eda6e813d7ca and 8b2a3dcc37b596de44f096241777b8a5768219e3.

📒 Files selected for processing (1)

• packages/shared/src/errors/missingExpiredTokenError.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (10)

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

All code must pass ESLint checks with the project's configuration

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*.{js,jsx,ts,tsx,json,md,yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use Prettier for consistent code formatting

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

packages/**/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

TypeScript is required for all packages

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Follow established naming conventions (PascalCase for components, camelCase for variables)

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

packages/**/src/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

packages/**/src/**/*.{ts,tsx,js,jsx}: Maintain comprehensive JSDoc comments for public APIs Use tree-shaking friendly exports Validate all inputs and sanitize outputs All public APIs must be documented with JSDoc Use dynamic imports for optional features Provide meaningful error messages to developers Include error recovery suggestions where applicable Log errors appropriately for debugging Lazy load components and features when possible Implement proper caching strategies Use efficient data structures and algorithms Implement proper logging with different levels

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*.ts?(x)

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use proper TypeScript error types

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/typescript.mdc)

**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs Use proper type annotations for variables and parameters where inference isn't clear Avoid any type - prefer unknown when type is uncertain, then narrow with type guards Implement type guards for unknown types using the pattern function isType(value: unknown): value is Type Use interface for object shapes that might be extended Use type for unions, primitives, and computed types Prefer readonly properties for immutable data structures Use private for internal implementation details in classes Use protected for inheritance hierarchies Use public explicitly for clarity in public APIs Use mixins for shared behavior across unrelated classes in TypeScript Use generic constraints with bounded type parameters like <T extends { id: string }> Use utility types like Omit, Partial, and Pick for data transformation instead of manual type construction Use discriminated unions instead of boolean flags for state management and API responses Use mapped types for transforming object types Use conditional types for type-level logic Leverage template literal types for string manipulation at the type level Use ES6 imports/exports consistently Use default exports sparingly, prefer named exports Document functions with JSDoc comments including @param, @returns, @throws, and @example tags Create custom error classes that extend Error for specific error types Use the Result pattern for error handling instead of throwing exceptions Use optional chaining (?.) and nullish coalescing (??) operators for safe property access Let TypeScript infer obvious types to reduce verbosity Use const assertions with as const for literal types Use satisfies operator for type checking without widening types Declare readonly arrays and objects for immutable data structures Use spread operator and array spread for immutable updates instead of mutations Use lazy loading for large types...

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*.{js,ts,jsx,tsx}

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Use ESLint with custom configurations tailored for different package types

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*.{js,ts,jsx,tsx,json,md,yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Use Prettier for code formatting across all packages

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

**/*

⚙️ CodeRabbit configuration file

If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes.

**/*: Only comment on issues that would block merging, ignore minor or stylistic concerns. Restrict feedback to errors, security risks, or functionality-breaking problems. Do not post comments on code style, formatting, or non-critical improvements. Keep reviews short: flag only issues that make the PR unsafe to merge. Group similar issues into a single comment instead of posting multiple notes. Skip repetition: if a pattern repeats, mention it once at a summary level only. Do not add general suggestions, focus strictly on merge-blocking concerns. If there are no critical problems, respond with minimal approval (e.g., 'Looks good'). Do not add additional review. Avoid line-by-line commentary unless it highlights a critical bug or security hole. Highlight only issues that could cause runtime errors, data loss, or severe maintainability issues. Ignore minor optimization opportunities, focus solely on correctness and safety. Provide a top-level summary of critical blockers rather than detailed per-line notes. Comment only when the issue must be resolved before merge, otherwise remain silent. When in doubt, err on the side of fewer comments, brevity and blocking issues only. Avoid posting any refactoring issues.

Files:

• packages/shared/src/errors/missingExpiredTokenError.ts

🧬 Code graph analysis (1)

packages/shared/src/errors/missingExpiredTokenError.ts (1)

packages/shared/src/error.ts (3)

• MissingExpiredTokenError (6-6)
• ClerkAPIResponseError (4-4)
• isClerkAPIResponseError (4-4)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (25)

• GitHub Check: Integration Tests (nextjs, chrome, 15)
• GitHub Check: Integration Tests (nextjs, chrome, 16)
• GitHub Check: Integration Tests (machine, chrome, RQ)
• GitHub Check: Integration Tests (machine, chrome)
• GitHub Check: Integration Tests (billing, chrome, RQ)
• GitHub Check: Integration Tests (quickstart, chrome, 15)
• GitHub Check: Integration Tests (nuxt, chrome)
• GitHub Check: Integration Tests (quickstart, chrome, 16)
• GitHub Check: Integration Tests (handshake, chrome)
• GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
• GitHub Check: Integration Tests (billing, chrome)
• GitHub Check: Integration Tests (custom, chrome)
• GitHub Check: Integration Tests (react-router, chrome)
• GitHub Check: Integration Tests (vue, chrome)
• GitHub Check: Integration Tests (tanstack-react-start, chrome)
• GitHub Check: Integration Tests (localhost, chrome)
• GitHub Check: Integration Tests (generic, chrome)
• GitHub Check: Integration Tests (sessions:staging, chrome)
• GitHub Check: Integration Tests (handshake:staging, chrome)
• GitHub Check: Integration Tests (express, chrome)
• GitHub Check: Integration Tests (ap-flows, chrome)
• GitHub Check: Integration Tests (sessions, chrome)
• GitHub Check: Integration Tests (astro, chrome)
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: semgrep-cloud-platform/scan

🔇 Additional comments (1)

packages/shared/src/errors/missingExpiredTokenError.ts (1)

1-45: Looks good.

The error class is well-structured with proper type guards and comprehensive documentation. No blocking issues found.

---

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

[pkg-pr-new[bot]]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 8b2a3dc

[blacksmith-sh[bot]]

Found 23 test failures on Blacksmith runners:

Test	View Logs
[chrome] › integration/tests/elements/ next-sign-in.test.ts:134:7 › Next.js Sign-In Flow @elements › long-running--elements.ne xt.appRouter › can reset password	View Logs
[chrome] › integration/tests/elements/ otp.test.ts:196:9 › OTP @elements › long-running--elements.next.appRouter › Type: segme nted-otp › should forward-delete char when pressing delete	View Logs
[chrome] › integration/tests/machine-auth/ api-keys.test.ts:184:7 › Next.js API key auth within routes @nextjs › should handle mul tiple token types	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:110:9 › pricing table @billing › long-running--withBilling.astro. node › when signed in flow › subscribes to a plan	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:110:9 › pricing table @billing › long-running--withBilling.next.a ppRouter › when signed in flow › subscribes to a plan	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:110:9 › pricing table @billing › long-running--withBilling.vue.vi te › when signed in flow › subscribes to a plan	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:221:7 › pricing table @billing › long-running--withBilling.astro. node › user is prompted to add email before checkout	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:221:7 › pricing table @billing › long-running--withBilling.next.a ppRouter › user is prompted to add email before checkout	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:250:7 › pricing table @billing › long-running--withBilling.next.a ppRouter › starts free trial subscription for new user	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:456:9 › pricing table @billing › long-running--withBilling.vue.vi te › in UserProfile › renders pricing table, subscribes to a plan, revalidates payment method on complete and then downgrades to free	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:80:9 › pricing table @billing › long-running--withBilling.astro.n ode › when signed in flow › when signed in, clicking get started button opens checkout drawer and shows free plan as active	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:80:9 › pricing table @billing › long-running--withBilling.next.ap pRouter › when signed in flow › when signed in, clicking get started button opens check out drawer and shows free plan as active	View Logs
[chrome] › integration/tests/ pricing-table.test.ts:80:9 › pricing table @billing › long-running--withBilling.vue.vit e › when signed in flow › when signed in, clicking get started button opens checkout dr awer and shows free plan as active	View Logs
[chrome] › integration/tests/ session-tasks-multi-session.test.ts:33:9 › session tasks multi-session flow @nextjs › l ong-running--next.appRouter.withSessionTasks › when switching sessions, navigate to tas k	View Logs
[chrome] › integration/tests/ sign-in-flow.test.ts:101:7 › sign in flow @generic @nextjs › long-running--next.appRout er.withEmailCodes › can reset password	View Logs
[chrome] › integration/tests/ sign-in-flow.test.ts:101:7 › sign in flow @generic @nextjs › long-running--next.appRout er.withEmailCodes › can reset password	View Logs
[chrome] › integration/tests/ sign-in-flow.test.ts:101:7 › sign in flow @generic @nextjs › long-running--next.appRout er.withEmailCodes › can reset password	View Logs
[chrome] › integration/tests/ sign-in-flow.test.ts:101:7 › sign in flow @generic @nextjs › long-running--next.appRout er.withEmailCodes › can reset password	View Logs
[chrome] › integration/tests/ sign-in-flow.test.ts:101:7 › sign in flow @generic @nextjs › long-running--react.vite.w ithEmailCodes › can reset password	View Logs
[chrome] › integration/tests/ sign-in-or-up-flow.test.ts:115:9 › sign-in-or-up flow @nextjs › long-running--next.appR outer.withSignInOrUpFlow › sign-in › can reset password	View Logs
[chrome] › integration/tests/ sign-in-or-up-flow.test.ts:115:9 › sign-in-or-up flow @nextjs › long-running--next.appR outer.withSignInOrUpFlow › sign-in › can reset password	View Logs
[chrome] › integration/tests/ sign-in-or-up-flow.test.ts:115:9 › sign-in-or-up flow @nextjs › long-running--next.appR outer.withSignInOrUpFlow › sign-in › can reset password	View Logs
[setup] › integration/tests/ global.setup.ts:7:6 › start long running apps ─────────────────────	View Logs

[bratsos]

!snapshot

[clerk-cookie]

Hey @bratsos - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.1-snapshot.v20251112130032
@clerk/astro	2.15.1-snapshot.v20251112130032
@clerk/backend	2.22.0-snapshot.v20251112130032
@clerk/chrome-extension	2.8.1-snapshot.v20251112130032
@clerk/clerk-js	5.108.0-snapshot.v20251112130032
@clerk/elements	0.23.82-snapshot.v20251112130032
@clerk/clerk-expo	2.19.1-snapshot.v20251112130032
@clerk/expo-passkeys	0.4.18-snapshot.v20251112130032
@clerk/express	1.7.49-snapshot.v20251112130032
@clerk/fastify	2.6.1-snapshot.v20251112130032
@clerk/localizations	3.27.3-snapshot.v20251112130032
@clerk/nextjs	6.35.1-snapshot.v20251112130032
@clerk/nuxt	1.12.1-snapshot.v20251112130032
@clerk/clerk-react	5.54.1-snapshot.v20251112130032
@clerk/react-router	2.2.1-snapshot.v20251112130032
@clerk/remix	4.13.16-snapshot.v20251112130032
@clerk/shared	3.33.1-snapshot.v20251112130032
@clerk/tanstack-react-start	0.27.1-snapshot.v20251112130032
@clerk/testing	1.13.15-snapshot.v20251112130032
@clerk/themes	2.4.36-snapshot.v20251112130032
@clerk/types	4.99.1-snapshot.v20251112130032
@clerk/vue	1.15.1-snapshot.v20251112130032

Tip: Use the snippet copy button below to quickly install the required packages. @clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

[bratsos]

!snapshot

[clerk-cookie]

Hey @bratsos - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20251211120550
@clerk/astro	3.0.0-snapshot.v20251211120550
@clerk/backend	3.0.0-snapshot.v20251211120550
@clerk/chrome-extension	3.0.0-snapshot.v20251211120550
@clerk/clerk-js	6.0.0-snapshot.v20251211120550
@clerk/dev-cli	1.0.0-snapshot.v20251211120550
@clerk/expo	3.0.0-snapshot.v20251211120550
@clerk/expo-passkeys	1.0.0-snapshot.v20251211120550
@clerk/express	2.0.0-snapshot.v20251211120550
@clerk/fastify	2.6.9-snapshot.v20251211120550
@clerk/localizations	4.0.0-snapshot.v20251211120550
@clerk/nextjs	7.0.0-snapshot.v20251211120550
@clerk/nuxt	2.0.0-snapshot.v20251211120550
@clerk/react	6.0.0-snapshot.v20251211120550
@clerk/react-router	3.0.0-snapshot.v20251211120550
@clerk/shared	4.0.0-snapshot.v20251211120550
@clerk/tanstack-react-start	1.0.0-snapshot.v20251211120550
@clerk/testing	2.0.0-snapshot.v20251211120550
@clerk/ui	1.0.0-snapshot.v20251211120550
@clerk/upgrade	2.0.0-snapshot.v20251211120550
@clerk/vue	2.0.0-snapshot.v20251211120550

Tip: Use the snippet copy button below to quickly install the required packages. @clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact