`onMutate` never actually runs synchronously

[sleexyz]

onMutate never actually runs synchronously because the result of #mutationCache.config.onMutate?.() is always awaited beforehand

Diff that fixes this:

diff --git a/node_modules/@tanstack/query-core/build/modern/mutation.js b/node_modules/@tanstack/query-core/build/modern/mutation.js
index 1bc7990..efbddd6 100644
--- a/node_modules/@tanstack/query-core/build/modern/mutation.js
+++ b/node_modules/@tanstack/query-core/build/modern/mutation.js
@@ -82,10 +82,12 @@ var Mutation = class extends Removable {
 try {
 if (!restored) {
 this.#dispatch({ type: "pending", variables, isPaused });
- await this.#mutationCache.config.onMutate?.(
- variables,
- this
- );
+ if (this.#mutationCache.config.onMutate) {
+ await this.#mutationCache.config.onMutate(
+ variables,
+ this
+ );
+ }
 const context = await this.options.onMutate?.(variables);
 if (context !== this.state.context) {
 this.#dispatch({

(Diff generated via patch-package to patch @tanstack/query-core@5.51.21)

[TkDodo]

We guarantee that onMutate runs synchronously, because it can in itself return a promise. We also await the result of it, it’s in your diff:

const context = await this.options.onMutate?.(variables);

So, no, I don’t think onMutate is meant to be syncronous.

[sleexyz]

Sure, the side-effects of onMutate could be asynchronous and be awaited. But my expectation is that the handler **fired** synchronously, esp since it's used for optimistic updates. For example, onMutate is currently unusable for optimistic updates to dndkit drag and drop state, bc the optimistic update fires asynchronously: https://stackoverflow.com/questions/79168785/react-query-with-dnd-kit-item-goes-back-to-original-position-for-a-split-second

…

On Mon, Mar 3, 2025 at 10:19 AM Dominik Dorfmeister < ***@***.***> wrote: We guarantee that onMutate runs synchronously, because it can in itself return a promise. We also await the result of it, it’s in your diff: const context = await this.options.onMutate?.(variables); So, no, I don’t think onMutate is meant to be syncronous. — Reply to this email directly, view it on GitHub <#8724 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALPSUNVXD7AMHHVJZRXGZT2SRXHBAVCNFSM6AAAAABYDVBFAOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMOJUG42DEMRQGY> . You are receiving this because you authored the thread.Message ID: ***@***.***> [image: TkDodo]*TkDodo* left a comment (TanStack/query#8724) <#8724 (comment)> We guarantee that onMutate runs synchronously, because it can in itself return a promise. We also await the result of it, it’s in your diff: const context = await this.options.onMutate?.(variables); So, no, I don’t think onMutate is meant to be syncronous. — Reply to this email directly, view it on GitHub <#8724 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALPSUNVXD7AMHHVJZRXGZT2SRXHBAVCNFSM6AAAAABYDVBFAOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMOJUG42DEMRQGY> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[TkDodo]

okay I think the change in the PR doesn’t hurt, so feel free to file it. However, this then means that the behaviour changes depending on if you have an onMutate defined on the mutationCache.

So I really wouldn’t rely on it being synchronous, as this would change as soon as you add onMutate on the cache.

[ayush-goyal]

@sleexyz I'm running into the same issue here, what did you do to fix the optimistic updates so that the onMutate handler is fired synchronously?

[samiulazm]

Is possible to solved the issue
@TkDodo
@sleexyz
Do you have any solution?

[TkDodo]

this still stands:

okay I think the change in the PR doesn’t hurt, so feel free to file it

[xxziiko]

@TkDodo
@sleexyz
Hello! I would like to work on this issue. I've seen the suggested diff in the description and will implement the fix along with a regression test to ensure onMutate runs synchronously. Please assign this to me if possible. Thanks!

[TkDodo]

we don’t assign people to issues. Don’t lick the cookie. You can always just do it.