Is it possible to receive field errors from onSubmit failure responses?

[lnhrdt]

I've been exploring adopting TanStack Form in my application. In our architecture, all form validation is done on the server, through submission. If the request is valid, the request succeeds. If the request is invalid, it returns a response of field errors (one or more).

I haven't found a way to adapt this architecture to TanStack Form. Is there a way to parse the response from an onSubmit failure (either thrown error or rejected promise) and apply the result to field errors?

[fulopkovacs]

TL;DR Currently, field errors can be set only from the field's validators, but we're planning to change this in the upcoming weeks.

Form validation on the server can be achieved using the form's onSubmitAsync validator, but unfortunately, there's no way to set field-specific errors in it.

You can validate the fields on the server by sending a fetch request in the field's onSubmitAsync validator (more about field validators here). Here's an example of an "age" field that sends its value to the server for validation when the user submits the form and returns an error message if the user is below 13 (the form will be also invalid in this case).

<form.Field
  name="age"
  validators={{
    onSubmitAsync: async ({value}) => {
         const below13: boolean = await validateAgeOnServer(value)
         return below13 ? 'You must be 13 to make an account' : undefined,
      }
  }}
>{...}</form.Field>

That's just what's currently possible, but your question sparked a conversation between the maintainers and we decided to implement a way to set field-specific errors from the form's validators. We already agreed on the API, and I picked up the task. I'm planning to do it in the upcoming weeks, but it's probably a tricky one, so please bear with me! 😅 I'm planning to ship it before v1.

[kane-chang]

Agreeing with @aadito123 , I appreciate the incredible work done so far, but I do believe server-side errors from form submission are valid form errors that need to be handled by the form library, even if they aren't validation errors. Having some control over which errors affect the form's canSubmit state would significantly help with this, for instance.

Take the use case of a simple email+password login, it shouldn't be the case that a form submission error from intermittent network error blocks resubmission where canSubmit is false because of the form-level error set using the recommended pattern above. This form behaviour dictates that the user needs to change their field inputs, which has nothing to do with the cause of the error.

In a case where there is a form without interactive fields, it would be even worse as it would be impossible for users to resubmit - canSubmit is stuck on false since the user has no way to "touch" the form and change canSubmit back to true to enable resubmission

The current alternative to this to track the error separately using useState for instance, but that defeats the purpose of using the form library to handle the form states elegantly. I wonder if there is a recommended approach to this I've missed anywhere, or if there's any plans to improve the handling around these form-level errors?

[andredewaard]

First of all, thank you @lnhrdt for the very well detailed breakdown.

Unfortunately I don't have a quick "do this" answer but that's definitely a scenario I'd like our library to facilitate, that is when you fire one single api call that:

1. Validates the data (might return errors)
2. Has side effects (creates a resource)
3. Returns data (an id you can use to navigate away)

Leaning into that direction I just merged #1489 (v1.11.0) that lets you set field errors all at onc:

form.setErrorMap({
  onChange: {
    form: 'global error',
    fields: {
      name: 'name is required',
      'interests[0].label': 'label is required',
    },
  },
})

It may not be the final solution, but I believe it should help for now.

Thanks for this answer! this does make a lot more sense than doing this in the onSubmit validator.
However, it could happen that the server responds with an error because the server was down for a brief second for example.
in that case only the 'form' error is set like

 form.setErrorMap({
>   onChange: {
>     form: e.message,
>   },
> })

The form is invalid at this point although its not and the user can't resubmit until a change is made in the form.

[Rinaldo]

Right now each item in the errorMap has form and fields as top level keys. What if there was another field called transient for unexpected network errors? A form with just a transient error would still have canSubmit=true so the user can retry

form.setErrorMap({
    onChange: {
        transient: "temporary service error, please try again later",
    },
})

[cgatian]

I think I found a workaround, but it's not pretty.
My use case was to display a general error message, such as "Not Authorized".

I built a notification component that subscribes to the form store's errorMap and isSubmitting. When onSubmit is detected I store that in local state, and then reset the form's errorMap omitting the onSubmit value. This preserves the field errors. This allows the form to be resubmitted. I then clear this error when the form is submitted, by subscribing to isSubmitting.

React Pseudo code:

    const [globalError, setGlobalError] = useState<any | undefined>(undefined);
    const errorMap = useFormStore(form.store, (state) => state.errorMap);
    const isSubmitting = useFormStore(form.store, (state) => state.isSubmitting);

    useEffect(() => {
      if (errorMap?.onSubmit) {
        setGlobalError(errorMap.onSubmit);
        // Clear the onSubmit error allowing resubmission if no other fields have errors
        setTimeout(() => {
          form.setErrorMap({
            ...errorMap,
            onSubmit: undefined,
          });
        }, 1);
      }
    }, [errorMap, form]);

    useEffect(() => {
      if (isSubmitting) {
        setGlobalError(undefined);
      }
    }, [isSubmitting]);

    return (
       <>
             {globalError && <span>{globalError</span>}
       </>
    )

[lnhrdt]

Previously I had marked this summary as the answer of this discussion but in light of continued comments here, I just unmarked it as the answer to try and get some fresh attention on the issues continuing to be discussed here.

[denisorehovsky]

I'm facing a similar issue. Waiting for the release of the improvement :)

[d3vzr]

For those struggling with setting field-specific errors from onSubmit, here's a workaround using setFieldMeta:

onSubmit: async ({ value }) => {
if (someCondition) {
setFieldMeta("fieldName", (prev) => ({
...prev,
errorMap: {
onChange: "Your error message here",
},
}));
return;
}
// Rest of your submit logic
}

This method allows you to set custom error messages for specific fields when handling submission failures or server-side validation responses. It's not ideal, but it works as a temporary solution until an official API is implemented for this use case.

[Ali-Albaker]

Exactly what I was looking for

[FourwingsY]

There is one-line solution i found.
formApi.fieldInfo.password.instance?.setErrorMap({ onSubmit: "Unknown Error Occurred" });

[fulopkovacs]

@Ali-Albaker and everyone else interested in this issue: now that #656 has been merged, we have an official API for setting field-level errors from the form's validators.

Here's the example in the docs.

This is how @d3vzr's workaround would look like using the official APIs:

validators: {
  // Note that this is the onSubmit validator
  onSubmit: async ({ value }) => {
    if (someCondition) {
       return {
         fields: {
           fieldName: "Your error message here",
         }
      }
    }
    return null
  }
}

You can read more about setting field-level errors in the form's validators in the docs: https://tanstack.com/form/latest/docs/framework/react/guides/validation#setting-field-level-errors-from-the-forms-validators

[hhwangS27]

It is so weird that we need to use validator to do the actual submit. hmm...

[andremonteiro95]

What's the way to integrate with Query's useMutation? I want to use useMutation to handle the submission, but I don't see a straightforward way to set field-level errors from the mutation's onError callback.

[MartinSchmidt123]

I successfully use

const form = useAppForm({
	defaultValues: initialValues,
	onSubmit: ({ value, formApi }) => {
		login.mutate(
			{
				data: {
					username: value.username,
					password: value.password,
				},
			},
			{
				onError: (error) => {						
					formApi.fieldInfo.password.instance?.setErrorMap({
						onSubmit: "Wrong password",
					});
				},
			},
		);
	},
});

based on #623 (reply in thread)

I also do not like submitting in a validator but having access to formApi in onSubmit seems to render this unnecessary. Not sure though if this is a new feature or not.

[markwoon]

All this definitely needs to be documented somewhere. Stumbled onto this thread while trying to deal with the same issues.

Is there way to make the response from a successul submission via validators.onSubmitAsync available in onSubmit (aka onSuccess) available within the framework? Or do I just have to maintain that state separately?

[lnhrdt]

@markwoon, I agree it's hard to discover this context. I just updated the accepted answer to spell out the available options and the tradeoffs for each. Hope it helps anyone else landing here!

[nova9]

I'm gonna handle forms myself. This is too much noise.

[qcho]

Hi. I too consider this should be handled better. It's super weird to change onSubmit with validators.onSubmitAsync

Imho a good idea would be to follow the practice of throwing something that is compatible with tasktack-form (I'm using tanstack-start).

My workaround was kind of something like that:

On the server I've created this:

const formFieldError = (field: string, message: string) => {
  return json(
    { onSubmit: { fields: { [field]: message } } },
    { status: HttpStatusCode.UnprocessableEntity },
  );
};

Inside the createServerFn I have something like:

    try {
      token = readCredentialsFromBase64(data.token);
    } catch (_e: unknown) {
      throw formFieldError("token", "Invalid token");
    }

Then on the client form submit I've created a type guard in order to underestand this is a form error from the backend and i want to set it to the form:

function isFormErrorMap<T>(
  // biome-ignore lint/suspicious/noExplicitAny: weird types
  _formApi: FormApi<T, any, any, any, any, any, any, any, any, any>,
  e: unknown
  // biome-ignore lint/suspicious/noExplicitAny: weird types
): e is FormValidationErrorMap<T, any, any, any, any, any, any, any, any> {
  return typeof e === "object" && e !== null && ("onSubmit" in e || "onServer" in e)
}

And then:

    onSubmit: async ({ value, formApi }) => {
      try {
        await serverCall({ data: value });
      } catch (e: unknown) {
        if (!isFormErrorMap(formApi, e)) {
          throw e;
        }
        formApi.setErrorMap(e);
      }
    },

The isFormErrorMap type guard can be improved but it has the minimal magic to make everything work. It's passing formApi just to infer the type. Maybe this could be refactored into a method of formApi somehow.

[alckordev]

I ran into the same scenario: how to handle a server API that returns an error—for example, on login, “invalid credentials.”

// actions.ts
"use server";

import { credentialsOpts, credentialsSchema } from "@/lib/forms/credentials";
import { createClient } from "@/lib/supabase/server";
import { createServerValidate, ServerValidateError } from "@tanstack/react-form/nextjs";

const serverLoginValidate = createServerValidate({
  ...credentialsOpts,
  onServerValidate: credentialsSchema,
});

export async function login(prev: unknown, formData: FormData) {
  try {
    const supabase = await createClient();

    const creds = await serverLoginValidate(formData);

    const { error } = await supabase.auth.signInWithPassword(creds);

    if (error) {
      throw new ServerValidateError({
        formState: {
          errorMap: {
            onServer: error.message,
          },
        },
      });
    }

    return {
      values: {
        status: "success",
      },
    };
  } catch (err) {
    if (err instanceof ServerValidateError) {
      return err.formState;
    }

    throw err;
  }
}

In this example, Supabase—like any other API—would return the “invalid credentials” error, and the way to display it on the frontend via onServer in the error map works perfectly. However, what bothers me is the type error this causes on any prop inside errorMap:

Type 'string' is not assignable to type 'undefined'.ts(2322)
types.d.ts(27, 5): The expected type comes from property 'onServer' which is declared here on type 'ValidationErrorMap<undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined>'

What I’m trying to figure out is how to resolve this annoying type error, because the value of onServer (or any prop in the error map) should be anything—it depends on the error format returned by the API. Generally, they all have a message, which is why my example uses error.message.

Now, as I mentioned, this works, since the frontend receives the onServer error in the state.

// login.tsx
"use client";

import { useActionState } from "react";
import { login } from "../actions";
import { initialFormState } from "@tanstack/react-form/nextjs";
import { mergeForm, useForm, useTransform } from "@tanstack/react-form";
import { credentialsOpts } from "@/lib/forms/credentials";
import { Field } from "@/components/ui/field";
import { Button } from "@/components/ui/button";

export const Login = () => {
  const [state, action] = useActionState(login, initialFormState);

  const form = useForm({
    ...credentialsOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
  });

  return (
    <form action={action} onSubmit={() => form.handleSubmit()}>
      <form.Field name="email">
        {(field) => (
          <Field.Root>
            <Field.Input
              type="email"
              name="email"
              placeholder="Email"
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
            />
            <Field.ErrorText>Test</Field.ErrorText>
            <pre>{JSON.stringify(field.state.meta.errors, null, 2)}</pre>
          </Field.Root>
        )}
      </form.Field>
      <form.Field name="password">
        {(field) => (
          <Field.Root>
            <Field.Input
              type="password"
              name="password"
              placeholder="Password"
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
            />
            <Field.ErrorText>Test</Field.ErrorText>
            <pre>{JSON.stringify(field.state.meta.errors, null, 2)}</pre>
          </Field.Root>
        )}
      </form.Field>
      <form.Subscribe selector={(formState) => [formState.canSubmit, formState.isSubmitting]}>
        {([canSubmit, isSubmitting]) => (
          <Button type="submit" disabled={!canSubmit} loading={isSubmitting}>
            Sign in
          </Button>
        )}
      </form.Subscribe>
      <pre>{JSON.stringify(state, null, 2)}</pre>
    </form>
  );
};

Any ideas on how to get rid of that type error?

[vafanassieff]

Is there a way to type the error in the errorMap instead of unknown ?

[philbates35]

@JosNun @vafanassieff and anyone else is trying to follow the advice from this thread and calling formApi.setErrorMap({form: '...'}) inside onSubmit when the backend fails and is struggling to get the form-level error to render without tsc / eslint-typescript errors, because tsc thinks that errorMap.onSubmit is always undefined - the best / least ugly workaround I've found so far is to define an empty validators.onSumbit with a form: undefined as string | undefined type assertion, as it seems this is the only way to get the correct undefined | string type inferred when it comes to read the value of errorMap.onSubmit. Basic working example:

   import { useForm } from "@tanstack/react-form";

   function LoginForm() {
     const form = useForm({
       defaultValues: {
         email: "",
         password: "",
       },
       validators: {
         // Must use type assertion to include `string` for form errors,
         // otherwise errorMap.onSubmit is inferred as `undefined` and
         // @typescript-eslint/no-unnecessary-condition flags the check as always falsy
         onSubmit: () => {
           return { form: undefined as string | undefined, fields: {} };
         },
       },
       onSubmit: async ({ value, formApi }) => {
         const response = await fetch("/api/login", {
           method: "POST",
           body: JSON.stringify(value),
         });

         if (response.status === 401) {
           formApi.setErrorMap({
             onSubmit: { form: "Invalid email or password", fields: {} },
           });

           return;
         }

         // Handle success...
       },
     });

     return (
       <form
         onSubmit={(e) => {
           e.preventDefault();
           void form.handleSubmit();
         }}
       >
         <form.Subscribe
           selector={(state) => [state.errorMap]}
           children={([errorMap]) =>
             errorMap.onSubmit ? <div role="alert">{errorMap.onSubmit}</div> : null
           }
         />
         {/* fields... */}
         <button type="submit">Sign in</button>
       </form>
     );
   }

Given that the ethos of this package seems to be that everything should be automatically inferred I can't say that I feel great about the explicit as string | undefined, or even just having to define the placeholder validators.onSubmit in the first place (the only reason I added it is to satisfy tsc), it definitely feels wrong but having read through this discussion as well as the docs and a few other related issues I found, I honestly don't know what the correct way to implement this and its possible there are downsides to this approach that I'm not aware of. But tsc & eslint are happy, and everything appears to work in the browser from my testing.

---

I think I speak for everyone on this thread when I say that it would be get some official guidance & some examples of how to properly implement this stuff - as has been said previously, a form submitting to a single end point (no dedicated validation end point) that either returns errors when there is a failure (either form-level or field-level) that we need to show to the user, or creates/updates the resource in the db on success and returns say an id that is needed for redirection, is surely one of the most common situations? I'm not using any SSR, just a plain old React SPA. Backends will always potentially be returning errors relating to business logic failures that the front end can't possible know about that still need to be shown to the user (you can't buy the ticket its now sold out, the publish date you provided is too far in the future etc)

Today is the first day that I've picked up this package to try it out, and I'm honestly very surprised that working out how to implement this was so difficult for me to work out 😅

EDIT: I realised after posting that even once you've resolved the type issues, you still have the fact that when the server responds with an error and you manually call formApi.setErrorMap, the value of form.isSubmittedSuccessfully is still true - because I presume this is derived from the validators only, not manual calls to formApi.setErrorMap()? So now I'm confused as to how I'm supposed to work out whether the form was successfully submitted or not...

[philbates35]

+1 for a new issue, I think that's probably the best way to get more eyes on this, I'm on holiday for the next month (typing this from phone), it would be great if someone could open a new issue summarising the problems we're all having and link to it here, thanks.

[lnhrdt]

As the person who originally opened this discussion and marked it as resolved, I would be supportive of opening a new one. I marked it resolved somewhat reluctantly, in deference to the maintainers’ position that the current design is acceptable, along with the workarounds that have been shared here. Even with a workaround in our codebase, the way we process server errors in our forms continues to be a frequent tripping hazard for our team.

I spent a fair amount of time putting together a detailed write-up of the issue, and I had hoped that level of specificity would move the discussion forward. I would subscribe to and contribute to a new issue or discussion on the topic. However, if folks feel strongly that reopening this discussion would be more productive than starting a new one, just say the word and I am happy to change this discussion back to "unanswered."

[rsslldnphy]

did someone create a new issue in the end? i'd be keen to subscribe to and contribute as well, this is the one wrinkle we've run into adopting tanstack form so far. i think re-opening this one could also work as there's a lot of useful context

[JClackett]

yeah looking for a way to user client + server validations and have them work together and currently it seems extremely hard :D

[lnhrdt]

Based on the continued community feedback here over the last couple of years, I'm changing this discussion back to "unanswered." CC: @tannerlinsley & @crutchcorn.