Open History to see the last commit
1---
2id: debugging
3title: Debugging Preact Usage
4---
5β
6This page covers common Preact and TypeScript problems when using TanStack Form.
7β
8## An input changes from uncontrolled to controlled
9β
10Every value rendered by a controlled input must exist in form-level
11`defaultValues` from the first render.
12β
13```tsx
14const form = useForm({
15 defaultValues: {
16 firstName: '',
17 subscribed: false,
18 },
19})
20```
21β
22Do not omit `defaultValues` or rely on a field-level default. When values come
23from an API, render a loading state before mounting the editable form or supply
24a complete fallback shape.
25β
26## A field value is `unknown`
27β
28Field names and values are inferred from `defaultValues`. Check that you have
29not widened the initial object to `Record<string, unknown>`, `any`, or an
30unrelated union. Prefer a concrete value type:
31β
32```tsx
33type Profile = { firstName: string; age: number }
34β
35const defaults: Profile = { firstName: '', age: 0 }
36const form = useForm({ defaultValues: defaults })
37```
38β
39For extremely large forms, split UI into typed components or scoped form/field
40groups instead of casting each field value.
41β
42## Type instantiation is excessively deep
43β
44This TypeScript error usually involves a very large recursive value shape, a
45widely inferred union, or an unsupported composition. Reduce it to the smallest
46form that reproduces the problem, keep `defaultValues` concrete, and avoid
47unnecessary generic wrappers.
48β
49If the minimal reproduction still fails, report it in the
50[TanStack Form issue tracker](https://github.com/TanStack/form/issues). Include
51the TypeScript version, the form value type, and the smallest failing field.
52β
53## Errors exist but are not displayed
54β
55`field.errors` respects the form's `errorVisibility` policy. Inspect
56`field.meta.original.errors` when debugging whether validation ran but the
57issues are intentionally hidden. Also confirm that the input calls
58`field.handleBlur` if the policy depends on `isBlurred`.