How to cancel/abort a mutation query?

[Merott]

Is there a way to cancel/abort mutation requests, similar to how cancelqueries does it for queries?

I can't seem to figure that out.

[TkDodo]

I don't think there is. The thing is: queries have no side-effect on the server, so you can run them as often as you want and also cancel them if you are no longer interested in the result. Per default, react-query will only ignore the result, but you can also attach a cancel method to the Promise to really abort the network request.

But as soon as you've fired off a mutation, once the backend has received it and has potentially started to update a database entry - how would you cancel that from the frontend... 🤷 .

Can you maybe elaborate on your use-case - what do you want to achieve?

[Merott]

Thanks for the quick response! You're right, I had similar thoughts before I posted the question.

My use case is that I'm saving changes to a textfield as the user types into it, debouncing the mutation by 300ms. I'm concerned about race conditions, although as you said, cancelling the mutation request is not a guarantee that the backend isn't going to carry out the update anyway.

On the other hand, debouncing by 300ms should be enough time to avoid a race condition for a small mutation. Unless we're dealing with a flakey, extremely slow network connection, but then again, I don't expect that to be the case very often, and I could invalidate the original query as well.

I'm probably overthinking it.

[kripod]

I just came across a similar use-case to @Merott’s but also use different debouncer delays based on the initiator (400ms for pointer and 1000ms for keyboard events). So, each Promise used for the mutation is cancelable on its own, throwing a custom cancelation error when the .cancel() method is invoked on any of them. The caveat is that the cancelation error shows up in the console.

Noticing that the retryer already has a CancellationError defined, I thought it should be exposed publicly. If a Promise executed by useMutation throws a CancellationError, then it should be caught by the inner implementation of useMutation and the mutation’s status should be set to 'canceled'.

What do you think about this proposal? (I didn’t want to open yet another thread about this, but would be excited to see a similar concept implemented into the project.)

[TkDodo]

I still don't understand what aborting a mutation would actually achieve. If I post the server: update the name of todoA to todoB, and the mutation is in-flight, and then I cancel it - how will the backend actually rollback the transaction? Yes, we can can probably cancel the promise - but what's the expected result in this scenario please?

[kripod]

useMutation could not only receive the result of a fetch call, but for instance, a cancelable Promise with a delay of 1000ms. If cancelation happens within the first 1000ms, a fetch call wouldn’t even be invoked.

[kripod]

When cancelation happens, the delayed Promise should be rejected with an instance of React Query’s CancelledError. Once that happens, the error should be caught, setting the mutation’s status to 'canceled'. In that case, onError/onSuccess/onSettled shouldn’t be called.

[TkDodo]

Okay so it’s not really about canceling the Network call, which is what the cancellation on useQuery allows, but more about debouching the mutation promise?

[kripod]

Yeah, exactly. But if there are multiple debouncers with different delays attached to the same callback, each of the debouncers should be cancelable individually.

Within the context of React Query, debouncing a Promise doesn’t seem like a good idea to me, as the MutationCache just keeps getting filled with the same, singleton-ish Promise. onSuccess/onSettled/onError events should only be called once when a debounced Promise finally has the chance to execute without its timer being reset. Unfortunately, onSettled is emitted multiple times for a debounced Promise, at least until a cancelation mechanism is available.

[lynxtaa]

There are a lot of cases for abortable mutations. For example, I'm sending files to the backend and my server can stop all the unnecessary work when request is aborted.

I think if mutationFunction returns a promise with a cancel property (similarly to query cancellation) than mutation.reset call or component unmount should trigger cancellation

[p6l-richard]

That's interesting. Do I interpret this correctly that your proposal still requires some logic to be implemented on the server to work 100%?

[lynxtaa]

Yeah, you can track request cancellation on backend and do a rollback/cleanup. In NodeJS, for example:

const http = require('http')

http
  .createServer((req, res) => {
    req.on('aborted', () => {
      console.log('aborted')
    })
  })
  .listen(3000)

[TkDodo]

That's interesting. Do I interpret this correctly that your proposal still requires some logic to be implemented on the server to work 100%?

Yes, I think so. Here is how I think what would need to happen:

• Frontend starts the mutation
• Backend picks it up and starts some work (database transaction, write files to disk or something similar). This might take some time, let's say some seconds.
• Frontend cancels the mutation
• Backend needs to get notified that the network request has been cancelled (I didn't find a lot on this topic, but I've seen that nestJs supports this for example)
• Backend needs to potentially un-do all the work it has already done (rollback db transaction, delete files)

I think the react-query involvement is not the most complex thing in this chain. For example, what happens if the mutation is cancelled after the database transaction has already been committed, but before the network request has been completed? What happens if the mutation is just a "send an email somewhere", how would you cancel that? And so on...

---

So yeah, I would actually accept a PR that adds mutation cancellation via the .cancel method on the promise returned from the mutationFn. But if we do that, I would expect a detailed documentation entry about what has to happen on the backend to make cancellation really do something. I do not want to get issue reports à la: "I cancelled the mutation but the entry is still in my database, why doesn't react-query mutation cancellation work??" because yeah, that's kinda what I am expecting to get if we say that we support this ;)

[tcvetkoska]

Hello I am interested what's happening with this mutation cancelling ? I can see that in useQueryClient there is a function for canceling mutation (cancelMutation()), I tried to use on a similar way as the cancelQuery(), the request is still working, but there is an error u console that informs me that the request has been canceled. Is it the expected behavior?

[TkDodo]

We've removed queryClient.cancelMutations for v4 because it was undocumented. The visible error is a byproduct of no cancelOptions being passed I guess.

[f0rr0]

calling mutation.cancel on a mutation in the mutation cache still does not abort the mutation. This method also does NOT seem to be deprecated in v4. the cancelMutations method is deprecated.

[TkDodo]

This method also does NOT seem to be deprecated in v4

This method is nowhere mentioned in the docs at all. I think I'm going to remove it in v4 as well, or at least make it private. It just cancels the retryer after a mutation has been removed, which currently only happens when you call .clear() on the queryCache ...

[f0rr0]

Yeah it should be private I guess. In the v4 changelog, there's a mention that this internal method can still be used in case someone wants it. That bit should also be removed from the changelog

[f0rr0]

It is trivial to write a wrapper to cancel mutations but it would be ideal if it was in built.

interface IFileUploadParams {
  presignedUploadUrl: string
  file: Blob
}

export const useFileUploadMutation = (
  options?: Omit<
    UseMutationOptions<void, AxiosError, IFileUploadParams>,
    'mutationFn'
  >
) => {
  const [progress, setProgress] = useState(0)
  const abortControllerRef = useRef<AbortController | null>(null)

  const mutation = useMutation<void, AxiosError, IFileUploadParams>((args) => {
    abortControllerRef.current = new AbortController()
    return axios.put(args.presignedUploadUrl, args.file, {
      onUploadProgress: (ev) => {
        setProgress(Math.round((ev.loaded * 100) / ev.total))
      },
      signal: abortControllerRef.current.signal,
    })
  }, options)

  const reset = useCallback(() => {
    abortControllerRef.current?.abort()
    mutation.reset()
    setProgress(0)
  }, [mutation.reset, setProgress])

  return { ...mutation, progress, abortControllerRef, reset }
}

[nathanhannig]

Example workaround to issues

  const abortControllerRef = React.useRef(null);
  const [state, setState] = React.useState("");
  React.useEffect(() => {
    return () => {
      abortControllerRef.current?.abort();
    };
  }, []);
  const createMutation = useMutation(
    (data) => {
      abortControllerRef.current = new AbortController();

      return create(data, abortControllerRef.current.signal);
    },
    {
      onSuccess: () => {
        console.log("success");
      },
      onError: (error) => {
        if (error.name !== "AbortError") {
          console.log("error");
          setState("error");
        }
      },
    }
  );

[jcready]

@TkDodo I understand that the mutation on the server-side will have side-effects that can't be easily undone so I'm fine with the actual request not getting aborted, but I'm still interested in a way to avoid having the callbacks/promise trigger their success/resolved callbacks when (for example) the inputs to the mutation change.

Here's an example: I have some long running process to validate some user input. It takes a very long time to complete so what happens is that the front-end submits the input to validate and gets a polling ID back from the server. We then poll the server using that polling ID on some interval until it says it has results. The initial submission (I would argue) is a mutation (we are changing state on the server) which gives us the polling ID back. If the user changes their inputs between when that mutation is run and when we get the polling ID back we want to simply drop that polling ID as it isn't useful any longer.

The logic for the component is something like:

const [input, setInput] = useState('');
const [pollingId, setPollingId] = useState(null);
const pollResults = useQuery({
  queryKey: ['poll validation', pollingId],
  queryFn: () => client.pollValidation(pollingId!),
  enabled: !!pollingId,
  refetchInterval: (r) => (r?.isComplete ? false : 10000),
});
const startValidation = useMutation(['start validation'], client.startValidation);
const onValidate = (e) => startValidation.mutate(input, { onSuccess: setPollingId });
const onInputChange = (e) => {
  // invalidate pending validation result
  setPollingId(null);
  setInput(e.target.value);
};

return (
  <form>
    <input type="text" value={input} onChange={onInputChange} />
    <button type="button" disabled={startValidation.isLoading} onClick={onValidate}>Validate</button>
    {!!pollResults.data?.isValid && (<button type="submit">Submit</button>)}
  </form>
);

The problem here is that even though we're invalidating the pending validation by setting the polling ID to null when the input changes, if the startValidation mutation hadn't finished yet then its onSuccess callback would still fire, triggering the polling to begin for a result that is no longer relevant. Obviously there are a few ways to mitigate this on our side:

1. Check that input is still the same in the onSuccess callback. This obviously works easily when the input is just a string literal that we can just check with triple equals comparison. Things get a lot more difficult if the input is some complex object.
2. Prevent the user from being able to change the input while the startValidation mutation isLoading. Sure, but we shouldn't be forced to change the UI behavior just to suite the limitations of react-query.

I would very much like to be able to invalidate/cancel the mutation callbacks even if the mutation itself continues to run.

[TkDodo]

interesting case. I know that the callbacks on .mutate are only called when the useMutation hook is still subscribed - so when the component unmounts, the callbacks on .mutate are not called (because the observer unsubscribes). callbacks on useMutation are always invoked.

So one thing you could do is put the useMutation into a separate component that you would then unmount to "cancel" it.

However, I would also argue that calling reset on the mutation would actually unsubscribe current observers. This is not happening. see here:

https://github.com/tannerlinsley/react-query/blob/c956f1af937f5f5186c7426dee1b07541264646b/src/core/mutationObserver.ts#L101-L105

observers are only removed if they unmount or if you call .mutate again:

https://github.com/tannerlinsley/react-query/blob/c956f1af937f5f5186c7426dee1b07541264646b/src/core/mutationObserver.ts#L113-L115

This seems like a bug to me. We set this.currentMutation to undefined, but we don't remove the observer. That could mean we are leaking observers if you call reset while the mutation is still ongoing.

If reset would remove the observer, callbacks wouldn't be called. I think that would cover your case, and it would also be more correct from what resetting a mutation should do. What do you think?

[jcready]

I think that's a perfect solution to my use case.

[TkDodo]

would you like to contribute it ? I'm a bit short on time these days 😅

[TkDodo]

@nathanhannig if you use the callbacks on .mutate for component specific side effects, they won't execute when the component has already unmounted.

This is documented here and I've also mentioned it here:
https://tkdodo.eu/blog/mastering-mutations-in-react-query#some-callbacks-might-not-fire

Further, the specifically mentioned warning has been removed in react 18 because it was a false positive most of the time, such as in the example that you describe.

see: reactwg/react-18#82

[codemile]

cough

    const {mutate} = useMutation(
        async ({signal}) => {
            /** do async work **/
            if (signal.aborted) {
                console.log('Was aborted.');
            }
        }
    );

   useEffect(() => {
      const x = new AbortController();
      mutate(x);
      return () => x.abort('bye');
   }, []);

[Estevete]

@TkDodo In my case, I have this use case. I want to abort / remove the mutation when I'm offline.

https://stackoverflow.com/questions/73444102/react-query-cancel-abort-mutation-if-paused-offline

[TkDodo]

answered.

[Estevete]

Thanks 😉

[hosseinmd]

I have a tool for swagger auto generator https://github.com/hosseinmd/swagger-typescript by this tool we could generate react hook from swagger which react-query is under the hood. So for canceling APIs, I was added a cancel function to all APIs promises. https://github.com/hosseinmd/swagger-typescript/blob/c4b74a56c847e4ae34d5d1b9e9527cc80024d5c2/src/javascript/files/httpRequest.ts#L26

[tianhuil]

I'm not sure if this is what the original poster wanted but I can imagine cancelling a use case for cancelling a query from onMutate. This might be because you have a mutation and you want to provide the user the opportunity (via a prompt) to stop it. This is most useful in a library like trpc which automatically creates mutations:

// trpc.delete is a trpc mutation
// confirmPrompt is a promise that returns the boolean selection from a user prompt.

const {mutateAsync} = trpc.delete.useMutation({
  onMutate: (data, variables, error, ctx) {
    if (!confirmPrompt('Do you want to delete the object?')) {
      ctx.cancelMutation()
    }
  }
})

return <button onClick={mustateAsync}>Delete Object</button>

This this something you would consider supporting @TkDodo ?

[TkDodo]

I would just move that confirmation out of the mutation:

const mutation = useMutation(...)

<button onClick={() => {
  if (confirmPrompt('Do you want to delete the object?')) {
     mutation.mutate()
  }
}}>click</button>

[budroco]

But as soon as you've fired off a mutation, once the backend has received it and has potentially started to update a database entry - how would you cancel that from the frontend...

I think the react-query involvement is not the most complex thing in this chain

I would just move that confirmation out of the mutation

@TkDodo You're being very helpful regarding working around the issue, but seem uninterested in actually solving it.
Why is that? What's wrong with mirroring the API of useQuery, i.e. giving us an AbortController to easily make our mutations cancellable? Is it harder than I'm expecting, are the resources not there or is it a feature you deem unfit for the project (I suppose by "you" I mean the whole project team, I just see that you have the maintainer badge)?

The thing is: queries have no side-effect on the server, so you can run them as often as you want

My mutations are idempotent, so there's no problem here.

Like some others here, I was just hoping for an easy way to debounce my requests while still being able to use the cache for optimistic updates using the very pattern from the Optimistic Updates documentation page:

...
useMutation({
  mutationFn: updateTodo,
  // When mutate is called:
  onMutate: async (newTodo) => {
    // Cancel any outgoing refetches
    // (so they don't overwrite our optimistic update)
    await queryClient.cancelQueries({ queryKey: ['todos'] })
...

My life would be very easy if there an AbortController passed to my mutation function and I could call something like cancelMutations here.

That said: Thanks for all the great work. Tanstack Query is great and so is your guide! I just think it could make our lives yet a bit better on this front.

[budroco]

For a bit of context: I'm using Tanstack Query's cache to control an input's state. On every change, I perform a mutation. It feel crazy to think about, but it works unexpectedly well for my use case!

In my current tests it even works to send a request on every key stroke, but that's what I'd eventually like to debounce.

[TkDodo]

You're being very helpful regarding working around the issue, but seem uninterested in actually solving it. Why is that?

Because I think that, and I did say that before, "solving the issue" would add more confusion. Mutations generally have a side-effect. If your mutation doesn't, then you're likely not looking at a mutation.

I can re-iterate my example: Let's make a mutation that sends an email to someone on the server. I click the button, it starts to send the email. I click the button again, is this now a new mutation? Should it automatically abort the previous mutation? If so, how does it stop the email from being sent? Currently, you can call a mutate function multiple times and will fire off multiple mutations. It will actually create multiple mutation entries and observers that are totally separated from each other. So, that would be a breaking change if you suggest auto-cancellation.

Even if we add it, I'm sure lots of people would expect the side-effect itself to be cancelled. "I cancelled the mutation but the entry still shows up in my database" are "bug reports" that I do NOT want to receive, yet would be very very likely to be reported. Because mutations are, imho, not easily abortable.

I'm using Tanstack Query's cache to control an input's state.

That sounds to me like you're clearly using it for something that it wasn't meant for. Why would you use an async state manager to control input state?

So, generally, you're requesting a feature that is not likely to work for the intended use-cases to make a pretty weird use-case easier. Sorry, that's a no from my side.

[ozzyfromspace]

Very late to the party, I know. My suggestion would be to send a UNIX timestamp with the updated value, and use that to avoid race conditions on the backend. Canceling the request doesn't help the backend much, because it's a mutation. All it does is tell the front-end not to care about the response. An even fancier approach might involve you caching the patch data on the server to avoid redundant database calls within a short space of time, then invalidating the server cache. One tech to achieve this is redis. Anyhoo, I was thinking about this race-condition mutation stuff earlier today, and this is how I'll be doing it. I appreciate the conversation here.

[Dennis-N8]

Here is a case when we show each time the result of the mutation + debounce.

https://evilmartians.com/chronicles/aborting-queries-and-mutations-in-react-apollo

@TkDodo How would you handle this case with React-Query (only show the response of the latest mutation)?

[TkDodo]

if you call mutate multiple times, useMutation will only return you the result of the latest invocation. But there is no way to actually cancel a mutation.

[benjamintd]

Does this mean that the mutations are fired in order?
Are they waiting for previous mutations to settle to avoid race conditions?

My use case can be described in the following timeline, using the Persist Client:

• User goes offline
• User adds a new Todo item (addItem mutation)
• User deletes that item (removeItem mutation)
• User goes back online

Are the mutations guaranteed to execute in order?
Would it be possible, if we realize that the addItem mutation still hasn't fired, to remove it from the queue while the user is still offline?

Thanks.

[James-Whitfield]

@benjamintd

I think I have a similar use case in my app where while offline I only want to send the last mutation that was called by the user while offline. I have used the meta object of a mutation to pass extra data which can then be used to remove the mutation from the cache while offline so that it can be replaced by the more recent one.

As an example:

const updateMutation = useMutation({
        mutationKey: ["save"],
        meta: {
            id,
        },
    });

const mutationCache = queryClient.getMutationCache();
const mutation = mutationCache
    .getAll()
    .find((a) => a.meta?.id == id);
if (mutation) {
    mutationCache.remove(mutation);
}

updateMutation.mutate({
    activity: data,
    contents: data.content,
    hiddenFields,
    values,
});

[Strajk]

My use is checking whether a user is logged-in in onMutate, and if not – redirecting to auth screen and ideally canceling the mutation.

onMutate: async function (variables, mutation) {
  const session = await getSession()
  if (!session?.user) {
    await signIn()
    // mutation.abort() 💡
  }
},

I know that I could check the user session in the components, but I'm developing an internal app so I wanted to handle this use case as globally as possible.

[derekbking]

I'd like to share my potential use case for abort signals in combination with mutations.

I've developed a file upload widget that uploads files in 100 MB chunks to my backend server. Each chunk is sent sequentially to the backend using Axios, wrapped around a useMutation function.

Sometimes, users may want to pause or even cancel the upload process. The widget provides the option to resume uploading files from the last successfully uploaded chunk. To achieve this, I've added my custom AbortSignal as an input to the mutation function, since useMutation doesn't natively support this feature.

However, there's a challenge with my current approach. The issue is that TanStack Query doesn't have any awareness of my AbortSignal. When I trigger the AbortSignal, Axios effectively cancels the request. Nevertheless, I have configured retries in case of network connectivity issues, which means that all retry attempts need to be exhausted before the mutation completes, and I can implement my error-handling logic.

Ideally, I want a way to cancel my mutation and also notify it that it should cease retrying when manually canceled.

[TkDodo]

you can set retry to a function and check if the signal has aborted it to stop retries

[derekbking]

Thank you! That's exactly what I was needing.

I see the signature is as follows retry: boolean | number | (failureCount: number, error: TError) => boolean.

It seems I will not be able to access the signal from the original TVariables from when the mutation was triggered. My initial thought is to manually check the error object details to see if it matches the details from when I trigger the abort.

This will solve my issue just fine. I was mainly curious if you had any specific recommendations. It seems potentially useful if the library provided TVariables to the retry callback. In my case it's not completely necessary, but I do think there are scenarios where having the initial mutation variables would be useful in the retry callback.

[TkDodo]

you can construct the error however you want by catching it inside the queryFn and then re-throwing a new error. If you want the signal or variables or whatever to be part of the error, that's the place to do it.

[boldurean]

Subscribed 👀 We also have some use cases where mutations need to be cancelled. Btw updates on the db could be easily rolled back after cancelation.

[zedrdave]

I think the biggest use-case for cancellable mutation has been mentioned above (and answered, I know… but more in a "can't do it for now, I'm afraid" kind of way): what if mutations pile up when offline, and we want to cancel overlapping or colliding mutations (to avoid race conditions when the app goes back online).

2 typical cases:

1. Mutation patches foo to be foo + 1, and is executed 5 times while offline (using cache to store the incremented value each time): by the time all 5 mutations are resumed, the server-side value of foo could be anything depending on network conditions…

2. Mutation calls post then delete on the same id: are there any guarantee that the mutation network calls will be sent in the same order, let alone complete in that order?

[TkDodo]

ad 1: I'd solve that by just sending an /inc mutation and let the server decide what to do with it. This is similar to having event driven reducers (dispatch({ type: 'inc' })) rather than having the logic in the UI and just having a setter in the store.

ad 2: yes, mutations will always be replayed in order, one after the other.

[zedrdave]

@TkDodo ad 1 was an extremely simplistic and reduced version of a real-world case. Real world could be [possibly debounced] version of a save-on-keystroke: you'd end up with 20 mutations for the same field update.

as 2: the sending is in order, but they are not chained, are they? (with enough mutations and bad luck, there is still a possibility that a delete is handled before a matching create)

[TkDodo]

yes, they are chained. If you have 5 mutations persisted, upon resume, we'll fire off the first one, wait for it to finish, then fire the second, wait for it to finish, then fire the third etc. code is here:

query/packages/query-core/src/mutationCache.ts

Lines 168 to 172 in 5290aa1

	pausedMutations.reduce(
	(promise, mutation) =>
	promise.then(() => mutation.continue().catch(noop)),
	Promise.resolve() as Promise<unknown>,
	),

[7ammer]

I also have an offline first app.

An official pattern to do something like the following would be very handy: If a post is deleted, remove all previous mutations using a filter.

It doesn't matter if one of the previous mutations reached the server as the latest mutation will be removing the post altogether. That is, if it even existed in the database to begin with.

Not removing the previous mutations will cause lots of redundant requests, and in my case temporarily shows deleted posts and then removes them again as the user goes back online and mutations are run in order.

For now, I've implemented something similar to @James-Whitfield's solution in the delete onMutate callback, which appears to be working as hoped:

        ...
        onMutate: (deleteArray) => {
            queryClient.cancelQueries({ queryKey: [journalEntriesKey] })
            .then(() => JournalEntriesInfiniteQueryCache.deleteMultiple(deleteArray));
            JournalEntryQueryCache.deleteMultiple(deleteArray);

            const mutationCache = queryClient.getMutationCache();
            mutationCache.getAll()
            .filter((a: any) => {
                let uuid = a.state?.variables?.uuid;
                return uuid && deleteArray.includes(uuid) && a.state.isPaused;
            })
            .forEach(mutation => mutationCache.remove(mutation));
        },
        ...

The docs state that mutationCache.getAll() is rarely used. I wonder if people who are implementing offline first patterns are going to increasingly need this.

[williamisnotdefined]

is it ok for cancelling a mutation?

useUploadFile.ts

import axios from "axios";

import { useMutation } from "@tanstack/react-query";

import { uploadFile } from "../api/uploadFile";

const useUploadFile = () => {
  const source = axios.CancelToken.source();

  const mutation = useMutation({
    mutationFn: (file: File) => uploadFile(file, source.token),
  });

  const abort = () => {
    source.cancel("Upload canceled by the user.");
  };

  return {
    ...mutation,
    abort,
    isCanceled: axios.isCancel,
  };
};

export default useUploadFile;

uploadFile.ts:

import { CancelToken } from "axios";

import { axiosInstance } from "@/core/axios";

export type FileUpload = {
  file: File;
};

export async function uploadFile(
  file: File,
  cancelToken?: CancelToken,
): Promise<FileUpload> {
  const formData = new FormData();
  formData.append("file", file);

  try {
    const { data } = await axiosInstance.put<FileUpload>(
      `/v1/upload/${file.name}`,
      formData,
      {
        cancelToken,
        headers: {
          "Content-Type": "multipart/form-data",
        },
      },
    );
    return data;
  } catch (error) {
    console.log("uploadFile: ", error);
    throw error;
  }
}

Usage:

        uploadMutate(file.file, {
          onSuccess: () => {
            // ...
          },
          onError(error) {
            if (error.name === "AbortError") {
              return;
            }

            // ....
          },
          async onSettled() {
            // if it is necessary here, also check for error, onSettle also provides this in its args
            // ...
          },
        });