Execution contract
- Use when
- Use when a query can become obsolete through navigation, parameter changes, or manual cancellation and the transport supports AbortSignal.
- Avoid when
- Do not simulate cancellation for non-cancellable work or writes that must complete atomically.
- Preconditions
- Confirm queryFn receives signal and forwards the same instance to every related I/O operation.
- Verification
- Change params during a slow request and observe the old request abort; cache reverts while the new request completes.
- Failure mode
- Continued network activity means signal was not forwarded; empty success means AbortError was converted into a normal return.
- Security
- Cancelling client wait does not undo completed server effects, so query cancellation is not transaction rollback.
Default behavior
When a query becomes unused, its promise may still complete and populate the cache by default. Cancellation aborts the promise and reverts Query state to its pre-fetch state only when the request layer consumes signal.
Request contract
Destructure signal from queryFn arguments and pass it to every related fetch. Preserve the AbortError rejection; catching it and returning empty data disguises cancellation as success.
import { queryOptions } from '@tanstack/react-query'
export const issueOptions = (issueId: string) => queryOptions({
queryKey: ['issues', 'detail', issueId] as const,
queryFn: async ({ signal }) => {
const response = await fetch(`/api/issues/${issueId}`, { signal })
if (!response.ok) throw new Error(`Issue request failed: ${response.status}`)
return response.json()
},
})Limits and manual cancellation
queryClient.cancelQueries can cancel by queryKey and also aborts the underlying promise after signal is consumed. The current guide explicitly excludes Suspense query hooks, so do not assume identical interaction semantics for useSuspenseQuery.