fix(mutation-observer): snapshot mutateOptions before dispatching callbacks

[okxint]

Fixes #11451

Problem

When mutate() is called inside an onSuccess handler, this.#mutateOptions is overwritten in place (via line 221) before onSettled fires in #notify(). This causes onSettled to fire with the next mutation's callbacks paired with the current mutation's data and variables.

mutation.mutate(1, {
  onSuccess: () => {
    // This overwrites this.#mutateOptions immediately
    mutation.mutate(2, { onSettled: secondOnSettled })
  },
  onSettled: firstOnSettled, // ← never called; secondOnSettled fires instead with data=1
})

Fix

Snapshot this.#mutateOptions into a local variable at the top of #notify(), before any callback fires. All three callbacks (onSuccess/onError/onSettled) then read from the snapshot and see the correct options for the mutation that actually settled.

const mutateOptions = this.#mutateOptions  // snapshot before any callback can overwrite it
if (mutateOptions && this.hasListeners()) {
  // ...use mutateOptions.onSuccess, mutateOptions.onSettled, etc.
}

This is the standard snapshot-before-dispatch pattern. Added a regression test in mutationObserver.test.tsx that fails before the fix and passes after.

Summary by CodeRabbit

• Bug Fixes
  • Ensured each mutation’s callbacks use that mutation’s own options, even when a callback starts another mutation.
  • Added regression coverage verifying that each mutation’s onSettled callback runs once with the correct data and variables.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6292817

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: TanStack/query/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: fd3eec8e-a2e6-42d5-bc32-aab31e912847

---

📥 Commits

Reviewing files that changed from the base of the PR and between a2e0eb2 and 6292817.

---

📒 Files selected for processing (2)

• packages/query-core/src/__tests__/mutationObserver.test.tsx
• packages/query-core/src/mutationObserver.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

Walkthrough

MutationObserver now uses a snapshot of per-call options when it dispatches success, error, and settled callbacks. A regression test covers a second mutation started from the first mutation’s onSuccess callback.

Changes

Mutation callback handling

Layer / File(s)	Summary
Snapshot callback options and verify nested mutations packages/query-core/src/mutationObserver.ts, packages/query-core/src/__tests__/mutationObserver.test.tsx	#notify uses the current notification’s option snapshot for success, error, and settled callbacks. The regression test checks that each mutation’s onSettled callback receives its own data and variables.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: sukvvon

---

Merge Risk: ⚪ Minimal · up to 62928

No actionable merge-blocking issue is identified; the change is ready for normal checks.

Pre-merge checks | 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check		The title clearly and concisely describes the primary change: snapshotting mutation options before dispatching callbacks.
Description check		The description clearly explains the problem, affected callbacks, implementation fix, linked issue, and regression test. It omits the template headings and checklist items, but it provides the key tec…
Linked Issues check		Issue #11451 requires each per-call callback to use the mutation that settled, including when a callback starts another mutation. MutationObserver.#notify() snapshots #mutateOptions before invokin…
Out of Scope Changes check		The diff contains one focused implementation change in packages/query-core/src/mutationObserver.ts and one regression test in packages/query-core/src/__tests__/mutationObserver.test.tsx. Both chan…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…

---

✨ 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

• X
• Mastodon
• Reddit
• LinkedIn

---

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