Debugging React Usage

This page covers common React and TypeScript problems when using TanStack Form.

An input changes from uncontrolled to controlled#

Every value rendered by a controlled input must exist in form-level defaultValues from the first render.

const form = useForm({
  defaultValues: {
    firstName: '',
    subscribed: false,
  },
})

Do not omit defaultValues or rely on a field-level default. When values come from an API, render a loading state before mounting the editable form or supply a complete fallback shape.

A field value is unknown#

Field names and values are inferred from defaultValues. Check that you have not widened the initial object to Record<string, unknown>, any, or an unrelated union. Prefer a concrete value type:

type Profile = { firstName: string; age: number }

const defaults: Profile = { firstName: '', age: 0 }
const form = useForm({ defaultValues: defaults })

For extremely large forms, split UI into typed components or scoped form/field groups instead of casting each field value.

Type instantiation is excessively deep#

This TypeScript error usually involves a very large recursive value shape, a widely inferred union, or an unsupported composition. Reduce it to the smallest form that reproduces the problem, keep defaultValues concrete, and avoid unnecessary generic wrappers.

If the minimal reproduction still fails, report it in the TanStack Form issue tracker. Include the TypeScript version, the form value type, and the smallest failing field.

Errors exist but are not displayed#

field.errors respects the form's errorVisibility policy. Inspect field.meta.original.errors when debugging whether validation ran but the issues are intentionally hidden. Also confirm that the input calls field.handleBlur if the policy depends on isBlurred.