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.

[runewolf7]

@lnhrdt @joeygrable94 This is very similar to an issue we are facing. I was considering the proposed workaround, using validators.onSubmit for the actual submission and form.onSubmit as the onSuccess handler... and it's intriguing. I think it would work for us in some cases. The trouble is that we sometimes need to return data from the submission to the onSuccess for navigation or firing analytics events etc, and I don't think there's a way to pass data from valdiators.onSubmit success over to form.onSubmit. I suppose we could just forgo calling onSubmit altogether which seems... wrong/bad?

We are using GraphQL along with Tanstack Query. With GraphQL, validation errors are returned as different types on the union of possible responses for a queries and mutations (along with success). We have no concept of separate validators. If we encounter a GQL error during submission, we parse the response type and then map the failure to the appropriate field OR if it's unrelated to a specific field we surface it as a global error (through RHF setError api).

I was under the impression that this was a pretty common architecture when working with GQL.

At any rate, I'm going to give using validators.onSubmit a try for a couple of PoCs and see how it goes! I agree that it's pretty unintuitive.

[gregorbg]

Just want to give this another spin from someone who recently tried adopting Tanstack-Form.

We're using Ruby on Rails as our backend, and for their ORM it's a pretty common model to do something like:

# This is a controller method which is wired to a `PATCH /users/{id}` URL.
# I would call this from the frontend using `fetch` or `axios` or whatever.
def update_user
  user = User.find(params[:id])

  update_params = params.require(:user).permit(:name, :email)
  user.name = update_params[:name]
  user.email = update_params[:email]
  
  # The `save` method on a Rails model runs validations and tries to persist to the DB if validations pass.
  # If they don't pass, then the method will return `false` and you can access the errors separately
  if user.save
    render status: :ok
  else
    render json: user.errors, status: :unprocessable_entity
  end
end

This snippet makes it so that the validation errors are returned from the same endpoint as the saving logic. I have read the other replies to figure out that you can actually submit the payload in the validators part and then treat the onSubmit as more of an afterSubmit. This might work, but feels hugely unintuitive.

Other alternatives:

• Provide a separate endpoint to run validations first. This is possible but undesirable as it (a) generates an extra API route for every single model and (b) it generates extra server load for non-trivial validations, because the validations will be run upon saving a second time anyways.
• Manually glue together an errorMap like in the answer at [Feature request] Global/root form error, independent of form fields #716 (reply in thread). Not sure if this is the "intended" way of doing things? Couldn't find any website documentation stating whether this is safe or not.
• Change our backend. Haha.

I would love to have more formal support for "injecting" errors from the outside, i.e. through some accessor on the return value of useForm. Especially seeing that your library boasts itself for being frontend framework agnostic, it seems counter-intuitive that it makes such strong assumptions about how your backend has to be structured. But I don't want to give up on this library yet because your other features are awesome!

TL;DR Is formApi.setErrorMap({ onSubmit: { fields: theErrorMapReturnedFromMyBackend } }) really the way to go?

[hhwangS27]

Good question @lnhrdt! (And sincere thanks for the patient tone with us as we figure out how to communicate this)

So if we think about how onSubmit is structured internally the code looks something like:

• Run validators.onSubmit sync validation
• Run validators.onSubmit async validation
• Run onSubmit if both don't have errors

Because of this, the idea is that all errors should be passed through our validators and only the successful logic should be in onSubmit

To be clear; we can still use your server's validation using the new feature + onSubmitAsync to handle the error setting internally for you rather than having to do things manually

Why the design does not allow onSubmit to have errors? Most of the backend design does not offer stand alone validator. They always design to return errors on submission. It is weird to do the submit in validator instead of the submit. This makes Tanstack Form really not good looking.

[lnhrdt]

Hey everyone! First, huge thanks to everyone volunteering time for TanStack Form (especially @fulopkovacs for the #656 solution and @crutchcorn for the overall design).

I originally kicked off this discussion because we needed to submit form data to an API that returns per-field validation errors, and it wasn't obvious how to feed those errors back into the form state. A year later people are still landing here confused, so I'm summarizing the two patterns you can use today and will make this the new accepted answer to help folks find it.

1. validators.onSubmitAsync (my go-to)

useForm({
  defaultValues: {firstName: '', lastName: '', emailAddress: ''},
  validators: {
    onSubmitAsync: async ({value: data, signal}) => {
      const response = await fetch('/api/users', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(data),
        signal: signal, // ✅ AbortSignal available
      })
      if (response.ok) {
        console.log(await response.json()) // "on success" handling here if you need access to the response body
      } else {
        // Must be an error map matching the shape of your form data
        // e.g. { firstName: 'Required', emailAddress: 'Must be valid email' }
        return await response.json()
      }
    },
  },
  onSubmit: () => {
    // consider this an optional "on success" hook
  },
})

Pros:

• Return a simple error map and the form wires up each field's error.
• Built-in AbortSignal support.

Cons:

• Submitting in a validator when a top-level onSubmit exists looks like a mistake. If you're on a large team, you might have to get used to explaining this.

2. onSubmit + manual field errors

useForm({
  defaultValues: {firstName: '', lastName: '', emailAddress: ''},
  onSubmit: async ({value: data, formApi}) => {
    const response = await fetch('/api/users', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(data),
      // ❌ AbortSignal not provided
    })
    if (response.ok) {
      console.log(await response.json())
    } else {
      const errors = await response.json()
      formApi.fieldInfo.firstName.instance?.setErrorMap({onSubmit: errors.firstName})
      formApi.fieldInfo.lastName.instance?.setErrorMap({onSubmit: errors.lastName})
      formApi.fieldInfo.emailAddress.instance?.setErrorMap({onSubmit: errors.emailAddress})
    }
  },
})

Pros:

• Submit logic lives where you'd expect.

Cons:

• You need boilerplate for each form you build (or clever iteration) to map errors into each fieldInfo call.
• No AbortSignal, so you can't cancel a slow request if the user navigates away.

---

We've found that validators.onSubmitAsync makes life easier overall. In our apps we usually wrap useForm (or useAppForm) to hide this bit of trickiness along with our own app-specific boilerplate conventions.

Lastly, I understand the design is meant to discourage patterns that "don't look good and are hard to follow"—@crutchcorn, I can appreciate that goal. But submitting to an API that returns per-field validation errors (upon submit, not separately beforehand) is extremely common. With full respect for everyone's volunteer time on this open-source project, it would be great if the maintainers could:

• Extend the top-level onSubmit or expose a top-level onSubmitAsync that
  • accepts an async function,
  • processes returned error-map objects, and
  • provides an AbortSignal; or
• Otherwise treat server-driven submit validation as a first-class use case.

I love how TanStack Router's throw redirect(...) is explicit and avoids hidden return-value semantics. I often imagine a similarly clear API for Form.

Thanks again for all the hard work on TanStack Form!

[Rinaldo]

Another con of the first approach is you lose access to the meta key from onSubmit. It would be great if meta was available in validators.onSubmit and onSubmitInvalid

[Balastrong]

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.

[pleunv]

One problem that I still run into with both solution 1 and 2 (and the new formApi.setErrorMap(…)) is that when you run into a server error you cannot immediately resubmit the form because it's marked invalid at that point, and requires you to change or touch a field before the form can be submitted again. I expect this for local validation because you need to change your data in order to get it to validate, however, this is not necessarily the case after a server submission as an error response can be both a remote validation error or simply a one-off, intermittent server error that would not reappear when you immediately resubmit.

I guess a combination of canSubmitWhenInvalid and onSubmitInvalid might be able to work around this but these do not appear to be documented anywhere, and it's unclear to me how they work. There's also the onServer key in the error map but that too is unclear and doesn't appear to be working.

edit: I found #1105 which arguments against this approach.

[JosNun]

I prefer approach #2 outlined by @lnhrdt above, solely because it's more intuitive. IMO, a validator having side effects is unintuitive, and a bit of code smell?

One downside of approach #2, though, is that form-level errors don't get typed for errorMap (ie, state.errorMap.onSubmit is typed as undefined). Is there a way to type these manually without having to type everything else?

Take the following use-case:

export function MinimalInviteForm() {
  const form = useAppForm({
    defaultValues: {
      email: ''
    },
    onSubmit: async ({ value, formApi }) => {
      return await mockAddUser({
        email: value.email,
      })
      .catch((e) => {
        console.log('Caught error during submission:', e);
        if (isUserExistsError(e)) {
          formApi.setErrorMap({
            onSubmit: {
              fields: {
                email: 'User already exists',
              },
            },
          });
        } else {
          formApi.setErrorMap({
            onSubmit: {
              form: 'Something went wrong',
              fields: {},
            },
          });
        }
      });
    },
  });

  return (
    <div>
        <form
          onSubmit={e => {
            e.preventDefault();
            form.handleSubmit();
          }}
        >
          <div>
            <form.AppField name='email'>
              {(field) => <field.InputField label='Email' type='email' autoFocus />}
            </form.AppField>
            <form.Subscribe selector={(state: any) => state.errorMap?.onSubmit}>
              {(errors) =>
                errors ? (
                  <div style={{ color: 'red' }}>
                    {errors.fields?.email ? `Email Error: ${errors.fields.email}` : null}
                  </div>
                ) : null
              }
            </form.Subscribe>
             <form.Subscribe selector={(state) => state.errorMap.onSubmit}>
              {(formError) =>
                /** formError is always typed as `undefined` here! */
                formError ? (
                  <div style={{ color: 'red' }}>
                    Field Validation: {Array.isArray(formError) ? formError.join(', ') : formError}
                  </div>
                ) : null
              }
            </form.Subscribe>
          </div>
          <div>
            <form.Subscribe
              selector={({ canSubmit}) => ({ canSubmit })}
            >
              {({ canSubmit}: any) => (
                <button
                  disabled={!canSubmit}
                  type='submit'
                >
                  Add User
                </button>
              )}
            </form.Subscribe>
          </div>
        </form>
    </div>
  );
}

In my experience, it's fairly common to handle the case where unknown errors occur during a form submission, but as of now, I've not been able to find a type-safe way of doing it with tanstack form?

[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.