fix(query-persist-client-core): catch errors when persisting in 'persistQueryClientSubscribe' to prevent unhandled promise rejections, and log them in development by kazbekaskarov · Pull Request #11678 · TanStack/query

kazbekaskarov · 2026-09-26T19:39:18Z

🎯 Changes

persistQueryClientSubscribe dropped the promise returned by persistQueryClientSave, so a failing persister.persistClient (e.g. QuotaExceededError from IndexedDB) or a throwing dehydrateOptions callback caused an unhandled promise rejection on every cache update.

The subscription now catches these errors and, in development, logs them with console.error + console.warn, consistent with how persistQueryClientRestore reports restore errors.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
I have followed the AI contribution policy and fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Bug Fixes
- Persistence failures during query updates are now caught and reported in development, preventing unhandled promise rejections. Errors encountered while preparing data for persistence are also reported, and persistence is skipped when that preparation fails. These protections apply to cache changes that trigger saves; production logging behavior remains unchanged.

…istQueryClientSubscribe' to prevent unhandled promise rejections, and log them in development

coderabbitai · 2026-09-26T19:41:11Z

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: TanStack/query
Branch: main
File: .coderabbit.yaml
Commit: 6f8a48d
Layers: Repository YAML
Review profile: CHILL
Plan: Advanced
Run ID: 1f7aa65e-d050-41b6-8f9e-ddfa872829d6

Commits

Reviewing files that changed from the base of the PR and between a32315c and 88b673d.

Files selected for processing: 1

packages/query-persist-client-core/src/persist.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

Walkthrough

persistQueryClientSubscribe now catches errors from cache-triggered saves and logs them outside production. Tests cover rejected persistence and errors during dehydration.

Changes: Persistence save error handling

Layer / File(s)	Summary
Catch and verify save errors `packages/query-persist-client-core/src/persist.ts`, `packages/query-persist-client-core/src/__tests__/persist.test.ts`, `.changeset/persist-subscribe-catch-save-errors.md`	Cache subscriptions use a shared callback that catches save errors and logs them outside production. Tests cover rejected persistence and dehydration errors. The changeset records the update.

Priority: Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: sukvvon

Merge Risk: Minimal · up to 88b67

No actionable issue remains before merge; complete the normal checks.

Security architecture risk: Low · up to a3231

Save failures are now handled instead of becoming unhandled rejections. The change does not alter which cache events trigger saves or who controls persisted storage, but production callers still receive no indication that a save failed.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

inferred — The changed failure handling applies to saves initiated by each subscribed query client and its supplied persister. The evidence does not establish the storage provider's scope or a broader deployment boundary.

Trust Boundaries and Controls

observed — The subscriber continues to filter cache events before invoking the existing save function. The change adds rejection handling rather than a new input route or storage authority.

Resilience and Maintainability Implications

observed — Subscriber save errors are logged in development but have no subscriber-level reporting path in production. Restore errors follow a separate path that performs cleanup and rethrows.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly and accurately summarizes the primary change: catching persistence errors in persistQueryClientSubscribe and logging them in development.
Description check		The description explains the problem, implementation, testing, checklist status, release impact, and changeset. It matches the required template and provides sufficient context.
Linked Issues check		The change satisfies issue `#11663`. `persistQueryClientSubscribe` now handles rejected `persistQueryClientSave` calls from query and mutation cache events. Development builds log the error and warning.…
Out of Scope Changes check		The changes stay within issue `#11663`. The source change handles save failures, the tests cover the required failure cases, and the changeset documents the same behavior. No unrelated product behavior …
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files.

Full details: Linked Issues check

Explanation

The change satisfies issue #11663. persistQueryClientSubscribe now handles rejected persistQueryClientSave calls from query and mutation cache events. Development builds log the error and warning. Tests cover rejected persistClient calls and exceptions from dehydrateOptions, including repeated cache updates.

Full details: Out of Scope Changes check

Explanation

The changes stay within issue #11663. The source change handles save failures, the tests cover the required failure cases, and the changeset documents the same behavior. No unrelated product behavior is shown.

Finishing Touches

🧪 Generate unit tests (beta)

Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

n-satoshi061 · 2026-09-27T03:55:31Z

Thanks for picking this up! The fix looks correct to me for both paths (a rejecting persistClient and a throwing dehydrateOptions callback).

One thing that might be worth a maintainer's call: right now, a failed save in production at least surfaces as an unhandled rejection, which error trackers like Sentry pick up via onunhandledrejection. With this change, it's caught and nothing is reported in production, so the failure becomes completely silent there.

That may well be the right tradeoff. I just wanted to point it out, since the restore side isn't silent in production (it calls removeClient() and rethrows).

kazbekaskarov · 2026-09-27T09:51:40Z

Hey guys! Can you check this PR please?
@lachlancollins @sukvvon

changeset-bot · 2026-10-26T16:35:24Z

🦋 Changeset detected

Latest commit: 88b673d

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

This PR includes changesets to release 24 packages

Name	Type
@tanstack/query-persist-client-core	Patch
@tanstack/preact-query-persist-client	Patch
@tanstack/preact-query	Patch
@tanstack/query-async-storage-persister	Patch
@tanstack/query-sync-storage-persister	Patch
@tanstack/react-query-persist-client	Patch
@tanstack/react-query	Patch
@tanstack/solid-query-persist-client	Patch
@tanstack/svelte-query-persist-client	Patch
@tanstack/angular-query-experimental	Patch
@tanstack/eslint-plugin-query	Patch
@tanstack/preact-query-devtools	Patch
@tanstack/query-broadcast-client-experimental	Patch
@tanstack/query-core	Patch
@tanstack/query-devtools	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/solid-query-devtools	Patch
@tanstack/solid-query	Patch
@tanstack/vue-query	Patch
@tanstack/svelte-query-devtools	Patch
@tanstack/svelte-query	Patch
@tanstack/vue-query-devtools	Patch
@tanstack/lit-query	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

nx-cloud · 2026-10-26T16:39:49Z

View your CI Pipeline Execution ↗ for commit 88b673d

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	⛔ Cancelled	1h 26s	View ↗

☁️ Nx Cloud last updated this comment at 2026-10-26 21:21:22 UTC

pkg-pr-new · 2026-10-26T16:41:41Z

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@11678

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@11678

@tanstack/lit-query

npm i https://pkg.pr.new/@tanstack/lit-query@11678

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@11678

@tanstack/preact-query-devtools

npm i https://pkg.pr.new/@tanstack/preact-query-devtools@11678

@tanstack/preact-query-persist-client

npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@11678

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@11678

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@11678

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@11678

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@11678

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@11678

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@11678

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@11678

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@11678

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@11678

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@11678

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@11678

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@11678

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@11678

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@11678

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@11678

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@11678

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@11678

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@11678

commit: 88b673d

fix(query-persist-client-core): catch errors when persisting in 'pers…

a32315c

…istQueryClientSubscribe' to prevent unhandled promise rejections, and log them in development

kazbekaskarov mentioned this pull request Sep 28, 2026

persistQueryClientSubscribe drops the persistQueryClientSave promise, causing unhandled rejections when persisting fails #11663

Open

mgarcia-improving mentioned this pull request Sep 28, 2026

fix(query-persist-client-core): catch persist errors in the subscriber #11718

Closed

4 of 5 tasks

TkDodo approved these changes Oct 26, 2026

View reviewed changes

Merge branch 'main' into fix/persist-subscribe-unhandled-rejection

88b673d

TkDodo closed this Oct 26, 2026

TkDodo reopened this Oct 26, 2026

Navigation Menu

Repository navigation

fix(query-persist-client-core): catch errors when persisting in 'persistQueryClientSubscribe' to prevent unhandled promise rejections, and log them in development - #11678

fix(query-persist-client-core): catch errors when persisting in 'persistQueryClientSubscribe' to prevent unhandled promise rejections, and log them in development#11678
kazbekaskarov wants to merge 2 commits into
TanStack:mainfrom
kazbekaskarov:fix/persist-subscribe-unhandled-rejection

kazbekaskarov commented Sep 26, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Sep 26, 2026 •

edited

Loading

Uh oh!

n-satoshi061 commented Sep 27, 2026

Uh oh!

kazbekaskarov commented Sep 27, 2026

Uh oh!

changeset-bot Bot commented Oct 26, 2026

Uh oh!

nx-cloud Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

kazbekaskarov commented Sep 26, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Sep 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

n-satoshi061 commented Sep 27, 2026

Uh oh!

kazbekaskarov commented Sep 27, 2026

Uh oh!

changeset-bot Bot commented Oct 26, 2026

🦋 Changeset detected

Uh oh!

nx-cloud Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kazbekaskarov commented Sep 26, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Sep 26, 2026 •

edited

Loading

nx-cloud Bot commented Oct 26, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 26, 2026 •

edited

Loading