--- id: Mutation title: Mutation --- Defined in: [packages/query-core/src/mutation.ts:138](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L138) Represents a single mutation attempt. A `Mutation` holds the mutation's options, state (data/error/status), and the `MutationObserver`s currently subscribed to it. Instances are created and managed internally by `MutationCache`; application code typically interacts with mutations indirectly through `QueryClient` or a framework hook like `useMutation`. Direct access to a `Mutation` instance is possible via `mutationCache.find()`/`getAll()` for inspecting cache state. ## Example ```ts const mutationCache = queryClient.getMutationCache() const mutation = mutationCache.find({ mutationKey: ['addPost'] }) ``` ## Extends - `Removable` ## Type Parameters ### TData `TData` = `unknown` ### TError `TError` = [`DefaultError`](../type-aliases/DefaultError.md) ### TVariables `TVariables` = `unknown` ### TOnMutateResult `TOnMutateResult` = `unknown` ## Constructors ### Constructor ```ts new Mutation(config: MutationConfig): Mutation; ``` Defined in: [packages/query-core/src/mutation.ts:155](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L155) #### Parameters ##### config `MutationConfig`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Returns `Mutation`\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> #### Overrides ```ts Removable.constructor ``` ## Properties ### gcTime ```ts gcTime: number; ``` Defined in: [packages/query-core/src/removable.ts:11](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L11) #### Inherited from ```ts Removable.gcTime ``` *** ### mutationId ```ts readonly mutationId: number; ``` Defined in: [packages/query-core/src/mutation.ts:146](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L146) *** ### options ```ts options: MutationOptions; ``` Defined in: [packages/query-core/src/mutation.ts:145](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L145) *** ### state ```ts state: MutationState; ``` Defined in: [packages/query-core/src/mutation.ts:144](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L144) ## Accessors ### meta #### Get Signature ```ts get meta(): Record | undefined; ``` Defined in: [packages/query-core/src/mutation.ts:187](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L187) The `meta` object passed in the mutation's options, if any. ##### Returns `Record`\<`string`, `unknown`\> \| `undefined` The mutation's `meta`, or `undefined` if none was set. ## Methods ### continue() ```ts continue(): Promise; ``` Defined in: [packages/query-core/src/mutation.ts:260](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L260) Resumes a mutation that is currently paused or was restored from a dehydrated, still-`pending` state. - If this mutation has an active retryer (it paused mid-attempt, e.g. due to the network mode or scope-based queuing), its retryer is resumed. - Otherwise, if the mutation's status is still `pending` (e.g. it was dehydrated while an attempt was in flight and never got a retryer in this instance), `execute` is called again with the last known variables. - Otherwise the mutation has already settled and this resolves immediately without running anything again. #### Returns `Promise`\<`unknown`\> A promise that settles with the resumed mutation: it rejects if the mutation fails. It resolves immediately if the mutation has already settled. #### See [Mutation#execute](#execute) #### Example ```ts // typically driven by reconnect handling, e.g. queryClient.resumePausedMutations() const mutation = mutationCache.find({ mutationKey: ['addPost'] }) await mutation?.continue() ``` *** ### destroy() ```ts destroy(): void; ``` Defined in: [packages/query-core/src/removable.ts:19](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L19) Clears the pending garbage collection timeout, so the entry is no longer scheduled for removal. A subclass may override this to release what it holds on to as well — `Query` also cancels any in-flight fetch. #### Returns `void` #### Inherited from ```ts Removable.destroy ``` *** ### execute() ```ts execute(variables: TVariables): Promise; ``` Defined in: [packages/query-core/src/mutation.ts:301](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutation.ts#L301) Runs the mutation function for the given variables through a retryer, and drives the mutation's state and lifecycle callbacks through to settlement. If this mutation's state is already `pending` when `execute` is called (i.e. it was restored, still in-flight, from a dehydrated state), the `onMutate` step is skipped and a `continue` action is dispatched to unpause it; otherwise a `pending` action is dispatched first, then the mutation cache's `onMutate` and the mutation's own `onMutate` option are awaited in that order, and the resulting context is stored. The mutation function is then run (subject to `retry`/`retryDelay`/ `networkMode`, and to the mutation cache's scope-based serialization). On success, the cache's `onSuccess`/`onSettled` callbacks run before the mutation's own `onSuccess`/`onSettled` options, a `success` action is dispatched, and the resolved data is returned. On failure, the same cache-then-option ordering is used for `onError`/`onSettled`, but each of those four callbacks is individually caught so that a throwing callback cannot mask the original error; an `error` action is then dispatched and the original error is re-thrown. #### Parameters ##### variables `TVariables` The variables passed to the `mutationFn`. #### Returns `Promise`\<`TData`\> A promise that resolves with the mutation's data, or rejects with its error. #### See [Mutation#continue](#continue) #### Example ```ts // Called internally by `MutationObserver.mutate` and `Mutation.continue` — // applications normally trigger mutations through those, not this method. const data = await mutation.execute(variables) ```