Сначала воспроизведите ошибку на одном объекте и отключите автоматический retry мутации. В Devtools запишите точный query key, значение cache до клика, optimistic value, HTTP status и порядок onMutate/onError/onSettled. Если onError срабатывает, но интерфейс не меняется, чаще всего откатывается другой key или более поздний refetch снова записывает optimistic данные.
Optimistic update — временная гипотеза UI, а не подтверждение сервера. Ей нужен обратный путь ещё до отправки запроса. Snapshot, который снимается после изменения, уже бесполезен; глобальный deep clone всего store создаёт другой риск — откат одной кнопки сотрёт независимые изменения пользователя.
Разложите сбой по временной шкале
| Момент | Cache | Что может пойти не так |
|---|---|---|
| T0 до mutate | server value A | Нет baseline в context |
| T1 onMutate | optimistic B | Идёт старый refetch A |
| T2 второй mutate | optimistic C | Оба rollback держат разные snapshots |
| T3 первый ответ 500 | неясно B или C | Старый rollback стирает C |
| T4 второй ответ 200 | server C | Invalidate не запущен |
| T5 refetch | authoritative C | Ответ A пришёл позже и перезаписал cache |
Отдельно проверьте, где нарисовано значение. Компонент может читать detail key `[item, id]`, а mutation обновляет только list key `[items]`; либо локальный useState перекрывает query data. Откат в cache проходит правильно, но пользователь продолжает видеть второй источник состояния.
Базовый цикл TanStack Query v5
useMutation({
mutationFn: updateTodo,
onMutate: async (next) => {
await queryClient.cancelQueries({ queryKey: ['todo', next.id] })
const previous = queryClient.getQueryData(['todo', next.id])
queryClient.setQueryData(['todo', next.id], old => ({ ...old, ...next }))
return { previous, id: next.id }
},
onError: (_error, _next, context) => {
queryClient.setQueryData(['todo', context.id], context.previous)
},
onSettled: (_data, _error, next) =>
queryClient.invalidateQueries({ queryKey: ['todo', next.id] })
})Документация TanStack Query рекомендует отменить исходящие refetch перед прямым изменением cache, сохранить предыдущее значение в onMutate и вернуть его как context для onError. invalidateQueries после завершения сверяет UI с сервером. В v5 callback onMutate для mutation может вернуть promise, и библиотека дождётся его до запуска mutationFn.
Две параллельные мутации требуют отдельного решения
- Запретить второй submit для одной сущности, пока первая команда pending.
- Сериализовать изменения одного объекта, но разрешить параллельность разных IDs.
- Добавить client mutation ID и откатывать только свой optimistic patch.
- Для простого добавления показывать pending row из mutation variables, не меняя общий cache.
- После conflict 409 получить серверную версию и явно показать, какое изменение не принято.
Полный snapshot удобен для одиночной мутации, но при конкуренции rollback первого запроса способен удалить успешный результат второго. Если бизнес допускает быстрые последовательные правки, храните обратный patch для конкретных полей и проверяйте mutation ID перед применением. Ещё проще — UI-only optimism: временная строка живёт рядом с результатом query до завершения и не затрагивает shared cache.
Ошибки отката прячутся в мелочах
- Убедиться, что mutationFn отклоняет promise на non-2xx, а не возвращает Response с 500 как успех.
- Проверить точное равенство query keys и тип ID: строка и число создают разные entries.
- Не мутировать объект snapshot по ссылке после его сохранения.
- Отменить подходящий refetch до setQueryData и дождаться cancelQueries.
- Проверить error boundary и локальный state, которые могут скрывать обновление cache.
- Оставить invalidate на success и error, если сервер остаётся доступен для сверки.
QueryClient документирует cancelQueries как особенно полезный для optimistic updates: поздний ответ активного запроса иначе способен перезаписать внесённое значение. При этом отмена не заменяет rollback mutation и не отменяет уже принятый сервером side effect.
Проверка без ручного клика
Автотест должен управлять порядком ответов. Задержите GET, запустите mutation, верните 500 и только потом разрешите старый GET; отдельно запустите две мутации одного ID, где первая падает, а вторая успешна. Проверяйте видимый текст, cache detail/list и финальный refetch. Исправление принято, когда ошибка возвращает подтверждённое состояние, успех второго запроса не теряется, а сообщение объясняет пользователю, что его изменение не сохранено.