Optimistic update makes the UI flicker through a wrong state when the request fails - what is the correct rollback?

Your suspicion is right, and there are two separate bugs producing the two symptoms.

The flicker is an in-flight refetch landing on top of your optimistic write. You write the optimistic value; a query that was already running finishes and writes the server's old value; your error handler then writes your snapshot. Three writes, and the middle one is not yours.

The fix is to cancel outgoing queries for that key before you write optimistically. Every good implementation of this starts with that step and it is the one people skip because the happy path works without it.

The wrong final value is your rollback writing a stale snapshot. If you captured the old value when the mutation was defined rather than immediately before the write, or if two mutations overlap, the value you restore is not the value that was there.

So the correct sequence, in order, and the order is the whole answer:

1. Cancel in-flight queries for the affected key
2. Read the current cached value and keep it as the rollback snapshot
3. Write the optimistic value
4. On error, write the snapshot back
5. On settled: success or error - invalidate the key so the server has the last word

Step 5 is what fixes the state that persists until you navigate away. Without it, a failed rollback is never corrected by anything.

The principle underneath the sequence above, which makes it easy to remember: the optimistic value is a guess with a deadline, and the server response ends it either way.

A lot of the mess comes from treating the mutation's own response as the new truth and writing it into the cache instead of refetching. That works until the server does something you did not model - a computed field, a timestamp, a side effect on a related record - and now your cache is a plausible fiction. Invalidating and letting the query refetch is slightly slower and always correct.

Two places this shows up:

Lists. Optimistically adding a row means inventing an id. When the server responds with the real one, you either reconcile carefully or you refetch. Refetch, unless you have measured that you cannot afford to.

Anything with ordering or aggregation. A toggle that changes a count somewhere else is exactly where hand-maintained cache updates go wrong, because you have to remember every derived thing.

The rule I use: optimistically update for feel, invalidate for truth. The optimistic write buys you the instant response; the invalidation makes sure that after a second, what is on screen is what is in the database. If those two ever disagree permanently, you have a bug you cannot see.

Settling on the wrong value is the more serious of the two symptoms and it is the one people notice last.

Worth checking one thing before you rewrite anything: is the key you are writing to the key the component is reading from?

A surprising share of "the rollback did not work" is that the optimistic write went to one key and the component is subscribed to another, a list key versus a detail key, or a key with a filter object that is constructed inline and therefore not identical between renders. The write succeeds, nothing complains, and the component never sees it. Then the eventual refetch corrects the screen and it looks like a timing bug.

How to check quickly: open the devtools for your query library and watch the cache while you toggle. You will see whether the optimistic write is landing on the entry the component uses. Thirty seconds and it rules out the entire category.

The related trap is a key built from an object literal. If any part of it is created fresh each render, or contains something non-serialisable, you can end up with more cache entries than you think - and your optimistic write goes to one while the screen reads another.

If your toggle affects both a list and a detail view, you need to handle both, and that is the case where invalidating on settled saves you from writing two rollbacks that have to agree.