fix(query-core): ensure onMutate runs synchronously when cache config is undefined (#8724) #10066

xxziiko · 2026-01-22T14:50:30Z

🎯 Changes

onMutate never actually runs synchronously #8724

Previously, mutationCache.config.onMutate was always awaited using optional chaining (await this.#mutationCache.config.onMutate?.()), which caused unnecessary async behavior even when the callback was undefined.

Changed to conditional check: only await when onMutate is actually defined
Added regression test to verify synchronous execution when cache config is not provided

✅ Checklist

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

🚀 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
- Corrected onMutate callback execution to run synchronously when cache-level configuration is undefined.
Tests
- Added test coverage for synchronous callback behavior in mutation operations.

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

… is undefined Fixes TanStack#8724

changeset-bot · 2026-01-22T14:50:35Z

🦋 Changeset detected

Latest commit: 1e71dcb

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

This PR includes changesets to release 19 packages

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

coderabbitai · 2026-01-22T14:50:59Z

📝 Walkthrough

Walkthrough

This PR patches TanStack Query core to ensure the onMutate callback executes synchronously when mutationCache.config.onMutate is undefined. The fix replaces optional chaining with an explicit null check before awaiting, preventing unnecessary async wrapping when no cache-level onMutate handler exists.

Changes

Cohort / File(s)	Summary
Changeset Documentation `.changeset/giant-apples-wear.md`	Patch version bump documenting the onMutate synchronous execution fix
Test Coverage `packages/query-core/src/__tests__/mutationCache.test.tsx`	New test verifying onMutate executes synchronously when cache-level onMutate is not defined
Core Logic `packages/query-core/src/mutation.ts`	Changed optional chaining call to explicit presence check before awaiting onMutate, enabling synchronous execution when cache-level handler is absent

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

fix(types): onMutateResult is always defined in onSuccess callback #9677 — Modifies mutation lifecycle callback invocation patterns in the same source file
fix(chore): report errors of useMutation callbacks asynchronously #9676 — Changes mutation error handling and callback invocation logic in mutation.ts

Suggested labels

package: query-core

Suggested reviewers

TkDodo

Poem

🐰 A hop and a skip, the callback runs fast,
No waiting around when cache-config's not vast,
Synchronous now when undefined's the way,
Mutations proceed without delay—hooray!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main fix: ensuring onMutate runs synchronously when cache config is undefined, directly matching the core change in mutation.ts and the test additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description follows the template structure with all required sections completed: Changes describe the fix with context, Checklist items are checked, and Release Impact is addressed with a changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

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 and usage tips.}

nx-cloud · 2026-01-22T14:51:03Z

View your CI Pipeline Execution ↗ for commit 1e71dcb

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	1m 3s	View ↗

☁️ Nx Cloud last updated this comment at 2026-01-23 07:36:06 UTC

pkg-pr-new · 2026-01-22T14:51:57Z

More templates

@tanstack/angular-query-experimental

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

@tanstack/eslint-plugin-query

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

@tanstack/query-async-storage-persister

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

@tanstack/query-broadcast-client-experimental

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

@tanstack/query-core

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

@tanstack/query-devtools

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

@tanstack/query-persist-client-core

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

@tanstack/query-sync-storage-persister

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

@tanstack/react-query

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

@tanstack/react-query-devtools

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

@tanstack/react-query-next-experimental

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

@tanstack/react-query-persist-client

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

@tanstack/solid-query

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

@tanstack/solid-query-devtools

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

@tanstack/solid-query-persist-client

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

@tanstack/svelte-query

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

@tanstack/svelte-query-devtools

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

@tanstack/svelte-query-persist-client

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

@tanstack/vue-query

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

@tanstack/vue-query-devtools

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

commit: 1e71dcb

sentry · 2026-01-23T07:48:20Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 42.68%. Comparing base (7afff91) to head (1e71dcb).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10066      +/-   ##
==========================================
+ Coverage   36.86%   42.68%   +5.81%     
==========================================
  Files         245      172      -73     
  Lines       11102     8258    -2844     
  Branches     2091     1679     -412     
==========================================
- Hits         4093     3525     -568     
+ Misses       6484     4343    -2141     
+ Partials      525      390     -135

Components	Coverage Δ
@tanstack/angular-query-experimental	`46.35% <ø> (ø)`
@tanstack/eslint-plugin-query	`∅ <ø> (∅)`
@tanstack/query-async-storage-persister	`43.85% <ø> (ø)`
@tanstack/query-broadcast-client-experimental	`24.39% <ø> (ø)`
@tanstack/query-codemods	`∅ <ø> (∅)`
@tanstack/query-core	`75.55% <100.00%> (+0.01%)`	⬆️
@tanstack/query-devtools	`3.38% <ø> (ø)`
@tanstack/query-persist-client-core	`80.12% <ø> (ø)`
@tanstack/query-sync-storage-persister	`84.61% <ø> (ø)`
@tanstack/query-test-utils	`∅ <ø> (∅)`
@tanstack/react-query	`29.00% <ø> (ø)`
@tanstack/react-query-devtools	`9.25% <ø> (ø)`
@tanstack/react-query-next-experimental	`∅ <ø> (∅)`
@tanstack/react-query-persist-client	`100.00% <ø> (ø)`
@tanstack/solid-query	`53.52% <ø> (ø)`
@tanstack/solid-query-devtools	`64.17% <ø> (ø)`
@tanstack/solid-query-persist-client	`100.00% <ø> (ø)`
@tanstack/svelte-query	`∅ <ø> (∅)`
@tanstack/svelte-query-devtools	`∅ <ø> (∅)`
@tanstack/svelte-query-persist-client	`∅ <ø> (∅)`
@tanstack/vue-query	`35.67% <ø> (ø)`
@tanstack/vue-query-devtools	`∅ <ø> (∅)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-01-23T13:30:13Z

🎉 This PR has been released!

@tanstack/query-core@5.90.20

Thank you for your contribution!

xxziiko added 2 commits January 22, 2026 21:37

chore: add changeset for onMutate sync fix

060bd43

fix(query-core): ensure onMutate runs synchronously when cache config…

1e71dcb

… is undefined Fixes TanStack#8724

github-actions bot added the package: query-core label Jan 22, 2026

TkDodo approved these changes Jan 23, 2026

View reviewed changes

TkDodo merged commit e7258c5 into TanStack:main Jan 23, 2026
9 of 10 checks passed

github-actions bot mentioned this pull request Jan 23, 2026

ci: Version Packages #10067

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(query-core): ensure onMutate runs synchronously when cache config is undefined (#8724) #10066

fix(query-core): ensure onMutate runs synchronously when cache config is undefined (#8724) #10066

xxziiko commented Jan 22, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Jan 22, 2026

Uh oh!

coderabbitai bot commented Jan 22, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 22, 2026

Uh oh!

Uh oh!

sentry bot commented Jan 23, 2026

Uh oh!

github-actions bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

fix(query-core): ensure onMutate runs synchronously when cache config is undefined (#8724) #10066

fix(query-core): ensure onMutate runs synchronously when cache config is undefined (#8724) #10066

Conversation

xxziiko commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 22, 2026

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 22, 2026

Uh oh!

Uh oh!

sentry bot commented Jan 23, 2026

Codecov Report

Uh oh!

github-actions bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

xxziiko commented Jan 22, 2026 •

edited

Loading

coderabbitai bot commented Jan 22, 2026 •

edited

Loading

nx-cloud bot commented Jan 22, 2026 •

edited

Loading