fix(query-core): reattach 'MutationObserver' to its mutation in 'onSubscribe' by lazerg · Pull Request #11172 · TanStack/query

lazerg · 2026-08-12T15:01:28Z

🎯 Changes

MutationObserver.onUnsubscribe() detaches the observer from its running mutation once the last listener goes away, and nothing ever put it back when a listener subscribed again. React runs that unsubscribe/resubscribe cycle on a component that keeps its state: <Activity mode="hidden"> and re-suspending boundaries in production, StrictMode in development. When it happens mid-mutation the mutation still settles normally in the MutationCache, but the detached observer never hears about it, so getCurrentResult() keeps handing its frozen pending snapshot to useSyncExternalStore. isPending stays true forever and the cache and the UI disagree permanently.

onSubscribe() now re-adds the observer to its current mutation and refreshes the snapshot, which is what QueryObserver already does for queries. Two cases are covered in mutationObserver.test.tsx: resubscribing while the mutation is still running, and resubscribing after it already settled.

Fixes #11171

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm run test:pr.

Local verification detail: both new tests fail on main (frozen at status: 'pending') and pass with the fix; pnpm run test:pr is green across 96 projects.

🚀 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
- Fixed mutation results remaining stuck in a pending state after subscriptions are removed and restored.
- Resubscribing now correctly reconnects to the active mutation and receives its final result, including successful completions.
Tests
- Added coverage for resubscribing during in-progress and completed mutations.

…bscribe'

coderabbitai · 2026-08-12T15:07:33Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b40b321e-8e7f-4ede-ad0c-8c8c76252533

📥 Commits

Reviewing files that changed from the base of the PR and between 6e3d521 and 130f8de.

📒 Files selected for processing (3)

.changeset/khaki-hoops-shake.md
packages/query-core/src/__tests__/mutationObserver.test.tsx
packages/query-core/src/mutationObserver.ts

🚧 Files skipped from review as they are similar to previous changes (3)

packages/query-core/src/mutationObserver.ts
packages/query-core/src/tests/mutationObserver.test.tsx
.changeset/khaki-hoops-shake.md

Included review availability: Your plan includes up to 10 reviews per rolling hour; 3 remain after this review.

📝 Walkthrough

Walkthrough

MutationObserver now reattaches its current mutation when a listener subscribes again. Tests cover in-flight and settled mutations, and a patch changeset documents the behavior.

Changes

Mutation observer resubscription

Layer / File(s)	Summary
Restore mutation attachment `packages/query-core/src/mutationObserver.ts`	`MutationObserver.onSubscribe()` re-registers the current mutation for the first listener and refreshes the current result.
Validate resubscription results `packages/query-core/src/__tests__/mutationObserver.test.tsx`, `.changeset/khaki-hoops-shake.md`	Tests verify successful results after resubscription during in-flight and settled mutations. The changeset records a patch release for `@tanstack/query-core`.

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

Merge Risk: ⚪ Minimal · up to 130f8

This localized fix reconnects mutation observers after resubscription and adds coverage for the affected lifecycle cases; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Subscriber
  participant MutationObserver
  participant Mutation
  Subscriber->>MutationObserver: subscribe
  MutationObserver->>Mutation: reattach current mutation
  MutationObserver->>MutationObserver: refresh current result
  Mutation->>MutationObserver: notify completion
  MutationObserver->>Subscriber: deliver successful result

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary fix: reattaching MutationObserver to its mutation during onSubscribe.
Description check	✅ Passed	The description covers the cause, fix, tests, verification, checklist, release impact, and linked issue.
Linked Issues check	✅ Passed	The implementation and tests address issue `#11171` by restoring MutationObserver updates after resubscription during or after a mutation.
Out of Scope Changes check	✅ Passed	The source change, regression tests, and changeset are directly related to the linked issue and stated pull request objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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.}

coderabbitai · 2026-08-18T08:02:13Z

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

nx-cloud · 2026-08-18T08:02:54Z

View your CI Pipeline Execution ↗ for commit 130f8de

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	4m 59s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1m 52s	View ↗

☁️ Nx Cloud last updated this comment at 2026-08-18 08:08:43 UTC

coderabbitai · 2026-08-18T08:05:46Z

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

pkg-pr-new · 2026-08-18T08:06:09Z

More templates

@tanstack/angular-query-experimental

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

@tanstack/eslint-plugin-query

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

@tanstack/lit-query

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

@tanstack/preact-query

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

@tanstack/preact-query-devtools

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

@tanstack/preact-query-persist-client

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

@tanstack/query-async-storage-persister

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

@tanstack/query-broadcast-client-experimental

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

@tanstack/query-core

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

@tanstack/query-devtools

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

@tanstack/query-persist-client-core

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

@tanstack/query-sync-storage-persister

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

@tanstack/react-query

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

@tanstack/react-query-devtools

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

@tanstack/react-query-next-experimental

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

@tanstack/react-query-persist-client

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

@tanstack/solid-query

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

@tanstack/solid-query-devtools

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

@tanstack/solid-query-persist-client

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

@tanstack/svelte-query

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

@tanstack/svelte-query-devtools

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

@tanstack/svelte-query-persist-client

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

@tanstack/vue-query

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

@tanstack/vue-query-devtools

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

commit: 130f8de

fix(query-core): reattach 'MutationObserver' to its mutation in 'onSu…

3b9a125

…bscribe'

TkDodo mentioned this pull request Aug 18, 2026

fix(query-core): re-attach MutationObserver to its in-flight mutation on resubscribe #11217

Closed

TkDodo approved these changes Aug 18, 2026

View reviewed changes

Merge branch 'main' into fix/issue-11171-mutation-observer-resubscribe

b812dab

Merge branch 'main' into fix/issue-11171-mutation-observer-resubscribe

130f8de

TkDodo merged commit 18c1c1e into TanStack:main Aug 18, 2026
9 checks passed

github-actions Bot mentioned this pull request Aug 18, 2026

ci: Version Packages #11206

Open

Navigation Menu

Uh oh!

Uh oh!

fix(query-core): reattach 'MutationObserver' to its mutation in 'onSubscribe' - #11172

fix(query-core): reattach 'MutationObserver' to its mutation in 'onSubscribe'#11172
TkDodo merged 3 commits into
TanStack:mainfrom
lazerg:fix/issue-11171-mutation-observer-resubscribe

lazerg commented Aug 12, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 12, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot commented Aug 18, 2026

Uh oh!

nx-cloud Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 18, 2026

Uh oh!

pkg-pr-new Bot commented Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

lazerg commented Aug 12, 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

Uh oh!

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

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot commented Aug 18, 2026

Uh oh!

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

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 18, 2026

Uh oh!

pkg-pr-new Bot commented Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lazerg commented Aug 12, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 12, 2026 •

edited

Loading

nx-cloud Bot commented Aug 18, 2026 •

edited

Loading