marmelab/react-admin · error · Error

useMutationWithMutationMode mutation requires parameters

Error message

useMutationWithMutationMode mutation requires parameters

What it means

Inside useMutationWithMutationMode, the react-query mutation function validates that variables were provided. If the mutate call receives null or undefined variables, the wrapper cannot merge them with its middleware pipeline and throws before invoking the mutationFn.

Source

Thrown at packages/ra-core/src/dataProvider/useMutationWithMutationMode.ts:121

            UseMutationWithMutationModeOptions<
                ErrorType,
                TData,
                TVariables
            >['onSettled']
        >();

    // We don't need to keep a ref on the onSuccess callback as we call it ourselves for optimistic and
    // undoable mutations. There is a limitation though: if one of the side effects applied by the onSuccess callback
    // unmounts the component that called the useUpdate hook (redirect for instance), it must be the last one applied,
    // otherwise the other side effects may not applied.
    const hasCallTimeOnSuccess = useRef(false);

    const mutation = useMutation<TData['data'], ErrorType, Partial<TVariables>>(
        {
            mutationKey,
            mutationFn: async params => {
                if (params == null) {
                    throw new Error(
                        'useMutationWithMutationMode mutation requires parameters'
                    );
                }

                return (
                    mutateWithMiddlewares
                        .current(params as TVariables)
                        // Middlewares expect the data property of the dataProvider response
                        .then(({ data }) => data)
                );
            },
            ...mutationOptions,
            onMutate: async (...args) => {
                if (mutationOptions.onMutate) {
                    const userContext =
                        (await mutationOptions.onMutate(...args)) || {};
                    return {
                        snapshot: snapshot.current,

View on GitHub (pinned to 051f511bb0)

Solutions

Always call mutate with a full variables object: mutate({ resource, id, data }).
Guard the handler: if (!params) return; before calling mutate.
Initialize the variables state with a complete default object.

Example fix

// before
const { mutate } = useMutationWithMutationMode(...);
onClick={() => mutate(params)}; // params may be undefined
// after
onClick={() => { if (params) mutate(params); }}

Defensive patterns

Strategy: validation

Validate before calling

if (params == null) {
  throw new TypeError('mutate requires a variables object');
}
mutate(params);

Type guard

const isDefined = <T,>(v: T | null | undefined): v is T => v != null;

Try / catch

try {
  mutate(params!);
} catch (e) {
  if (e instanceof Error && e.message.includes('requires parameters')) {
    notify('Nothing to submit', { type: 'warning' });
  } else throw e;
}

Prevention

Never call mutate() with zero arguments.
Initialize variables state with a complete default object.
Guard event handlers against undefined payloads.

When it happens

Trigger: Calling mutate() or mutate(null) / mutate(undefined) without a variables object; passing a variable that resolves to undefined at call time (e.g. an uninitialized state object).

Common situations: Buttons wired to mutate before form state initializes; event handlers calling mutate with an implicit undefined argument; optional-chained values like mutate(formValues?.params) where formValues is null.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of marmelab/react-admin@051f511bb0 (2026-08-30). Data as JSON: /api/errors/ec91c3d9d0a29792. Report an issue: GitHub.