Global, hook and .mutate/mutateAsync onError handler - which will be called

[gronnmann]

Let's say I define three onError handlers:

When creating the queryClient:

export const globalQueryClient = new QueryClient({
    queryCache: new QueryCache({
        onError: (error) => {
            handleGlobalError(error)
        }
    }),
    mutationCache: new MutationCache({
        onError: (error) => {
            handleGlobalError(error)
        }
    })
});

Afterwards, when defining cusotm hooks which call mutations:

export function useVerifyConnection() {
    const queryClient = useQueryClient();

    return useMutation<{ message: string }, Error, { systemId: number, integrationId: number }>({
        mutationFn: async ({ systemId, integrationId }) => {
            const response = await apiClient.post<{ message: string }>(
                `/integrations/${integrationId}/systems/${systemId}/verify/`
            );
            return response.data; // Ensure the response data is returned
        },
        onSuccess: (_, variables) => {
            queryClient.invalidateQueries({
                queryKey: ["integrations", variables.integrationId],
            });
        },
        onError: (error, variables) => {
            queryClient.invalidateQueries({
                queryKey: ["integrations", variables.integrationId],
            });
        },
    });
}

And finally, where it's used:

const verifyMutation = useVerifyConnection()

const handleVerify = () => {
        verifyMutation.mutate({
                systemId,
                integrationId: currentIntegration.id,
            },
            {
                onSuccess: () => {
                    toast.success("Verifisering vellykket");
                },
                onError: (error) => {
                    toast.error(handleGlobalError(error));
                },
            })
    }

Let's say the error fails. Which onError do get called?

From what I understood, the hook-definition one, and the one directly called with mutate both get called. But what about the global one, does it still trigger?
And does this behaviour change when using mutateAsync, as that one throws errors?

All help is appreciated!
Thank you!

[TkDodo]

The first one that gets called is the cache-level one defined on the MutationCache. After that, the one on useMutation. Those are both callbacks that can be async, which means you can await things and it will keep the mutation pending until those resolve. If the callback returns a rejected Promise, the mutation will go into error state as well (That’s more important for the onSuccess callback).

The last thing that gets called is the “observer-level” callback on mutate, but as you can see on the type definition, it returns void, not a Promise. This one happens after the mutation has finished, so you can’t affect its state anymore by awaiting or throwing.

And does this behaviour change when using mutateAsync, as that one throws errors?

no, it doesn’t change.