{"record":{"id":"01b7d4286979cc66","repo":"marmelab/react-admin","slug":"the-returnpromise-parameter-can-only-be-used-if-th","errorCode":null,"errorMessage":"The returnPromise parameter can only be used if the mutationMode is set to pessimistic","messagePattern":"The returnPromise parameter can only be used if the mutationMode is set to pessimistic","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/ra-core/src/dataProvider/useMutationWithMutationMode.ts","lineNumber":264,"sourceCode":"                }\n            );\n        } else {\n            mutateWithMiddlewares.current = mutationFnEvent;\n        }\n\n        // We need to keep the onSuccess callback here and not in the useMutation for undoable mutations\n        hasCallTimeOnSuccess.current = !!onSuccess;\n        // We need to store the onError and onSettled callbacks here to be able to call them in the useMutation hook\n        // so that they are called even when the calling component is unmounted\n        callTimeOnError.current = onError;\n        callTimeOnSettled.current = onSettled;\n\n        if (mutationMode) {\n            mode.current = mutationMode;\n        }\n\n        if (returnPromise && mode.current !== 'pessimistic') {\n            console.warn(\n                'The returnPromise parameter can only be used if the mutationMode is set to pessimistic'\n            );\n        }\n\n        snapshot.current = getSnapshotEvent(\n            getQueryKeysEvent(\n                { ...paramsRef.current, ...callTimeParams },\n                {\n                    mutationMode: mode.current,\n                }\n            )\n        );\n\n        if (mode.current === 'pessimistic') {\n            if (returnPromise) {\n                return mutation.mutateAsync(\n                    { ...paramsRef.current, ...callTimeParams },\n                    // We don't pass onError and onSettled here as we will call them in the useMutation hook side effects","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/marmelab/react-admin/blob/051f511bb0afb5ea565c2d3728bf4dab0a6fa5e0/packages/ra-core/src/dataProvider/useMutationWithMutationMode.ts#L246-L282","documentation":"In useMutationWithMutationMode, returning a promise only makes sense in pessimistic mutation mode, where the hook waits for the dataProvider call to finish. In undoable or optimistic modes the mutation resolves before the server call completes, so a returned promise would be meaningless; the hook warns when returnPromise is set with a non-pessimistic mode.","triggerScenarios":"Calling mutate(..., { returnPromise: true }) while mutationMode is 'undoable' or 'optimistic' (the default), either via options or an inline mutationMode override.","commonSituations":"Awaiting mutate() for form submission success handling but forgetting to set mutationMode: 'pessimistic'; copying examples that use returnPromise without the matching mode.","solutions":["Pass mutationMode: 'pessimistic' to the hook (or the mutate call) when using returnPromise: true.","Remove returnPromise and use onSuccess/onError callbacks if you want undoable/optimistic behavior.","If mode is configurable, guard: only set returnPromise when the resolved mode is pessimistic."],"exampleFix":"// before\nconst { mutate } = useCreate();\nawait mutate('posts', { data }, { returnPromise: true });\n// after\nconst { mutate } = useCreate();\nawait mutate('posts', { data }, { returnPromise: true, mutationMode: 'pessimistic' });","handlingStrategy":"validation","validationCode":"const canReturnPromise = (mutationMode ?? 'undoable') === 'pessimistic';\nif (needAwait && !canReturnPromise) throw new Error('Set mutationMode: \"pessimistic\" to use returnPromise');","typeGuard":"const isPessimistic = (m) => m === 'pessimistic';\nconst opts = { returnPromise: true, mutationMode: 'pessimistic' };\nif (opts.returnPromise && !isPessimistic(opts.mutationMode)) { /* fix before calling mutate */ }","tryCatchPattern":"try {\n  await mutate('posts', { data }, { returnPromise: true, mutationMode: 'pessimistic' });\n} catch (error) {\n  notify(error.message, { type: 'error' });\n}","preventionTips":["Pair returnPromise: true with mutationMode: 'pessimistic' in the same options object.","Prefer onSuccess/onError callbacks in optimistic/undoable flows.","Centralize mutation options in a helper that enforces this invariant."],"tags":["mutations","async","react-admin"],"backgroundTag":"return-promise-requires-pessimistic-mode","analyzedSha":"051f511bb0afb5ea565c2d3728bf4dab0a6fa5e0","analyzedAt":"2026-08-30T02:28:14.926Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}