fix(query-core): release mutation retryer after execute() settles

[okxint]

Summary

Mutation.execute() leaves #retryer set after the mutation settles. The retryer's resolved promise keeps the raw mutation result in memory for the mutation's entire lifetime — a second copy alongside the structurally-shared state.data, and persisting even after the mutation is removed from the cache.

This is the direct parallel to the Query.fetch() memory leak fixed in #11163. The fix is identical in structure.

Closes #11216

Root cause

// Before: #retryer stays set after execute() returns
this.#retryer = createRetryer({ ... })
try {
  const data = await this.#retryer.start()
  // ... callbacks ...
} finally {
  this.#mutationCache.runNext(this)  // ← #retryer is never cleared
}

Fix

// After: mirrors Query.fetch() from #11163
const retryer = (this.#retryer = createRetryer({ ... }))
try {
  const data = await retryer.start()
  // ... callbacks ...
} finally {
  if (this.#retryer === retryer) {  // identity guard for re-entrant execute()
    this.#retryer = undefined
  }
  this.#mutationCache.runNext(this)
}

The identity guard is the same as in query.ts — it prevents a re-entrant execute() call (e.g. from a MutationCache.onSuccess callback) from having its fresh retryer cleared by the outer finally.

Changes

• mutation.ts: apply the same 3-line fix as query.ts line 593-595
• mutation.ts: add get promise() to match Query's public API, enabling a parallel regression test
• mutations.test.tsx: add regression test that verifies mutation.promise is undefined after execute() settles (including re-entrant case)

All 25 tests pass.

Summary by CodeRabbit

• Bug Fixes

  • Improved mutation cleanup after execution completes, preventing settled operations from retaining unnecessary result data.
  • Preserved mutation results while ensuring active retry operations are correctly released.
  • Fixed handling of new mutation executions started during a success callback.

• New Features

  • Added access to the currently active mutation promise.

[coderabbitai]

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: 70c2751c-034a-44c7-b1ae-d54c24ae9dd6

📥 Commits

Reviewing files that changed from the base of the PR and between 34f7cee and 38cfb5b.

📒 Files selected for processing (3)

• .changeset/release-mutation-retryer.md
• packages/query-core/src/__tests__/mutations.test.tsx
• packages/query-core/src/mutation.ts

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

---

📝 Walkthrough

Walkthrough

Mutation.execute() now releases its settled retryer, exposes the active retryer promise, and preserves retryers created during re-entrant execution. Regression coverage verifies the lifecycle, and a patch changeset documents the release.

Changes

Mutation retryer cleanup

Layer / File(s)	Summary
Mutation execution lifecycle packages/query-core/src/mutation.ts	Mutation exposes the active promise, uses a local retryer during execution, and clears #retryer after settlement only when no newer retryer replaced it.
Retryer lifecycle validation and release metadata packages/query-core/src/__tests__/mutations.test.tsx, .changeset/release-mutation-retryer.md	Regression coverage verifies re-entrant promise replacement and retryer release. The changeset records a patch release for @tanstack/query-core.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 38cfb

The change releases mutation retryer state after execution settles while preserving re-entrant execution behavior; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• TanStack/query#11163: Applies the same settled-retryer cleanup pattern to Query.fetch().
• TanStack/query#11219: Also modifies Mutation.execute() and mutation retryer cleanup.
• TanStack/query#11218: Addresses the same mutation settled-retryer retention behavior.

Suggested reviewers: tkdodo

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the retryer cleanup after mutation execution settles.
Description check	✅ Passed	The description clearly explains the root cause, fix, regression coverage, tests, and release impact, despite not using the exact template headings.
Linked Issues check	✅ Passed	The changes satisfy the retryer cleanup and identity-guard requirements in [#11216], while appropriately following the parallel implementation in [#11163].
Out of Scope Changes check	✅ Passed	The changeset, implementation, public getter, and regression test all support the linked issue 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

• X
• Mastodon
• Reddit
• LinkedIn

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