Open History to see the last commit
1---
2id: debugging
3title: Debugging Lit Usage
4---
5β
6This page covers common Lit and TypeScript problems when using TanStack Form.
7β
8## An input renders an empty or undefined value
9β
10Every value bound to an input must exist in form-level `defaultValues` from the
11first render.
12β
13```ts
14private form = new TanStackFormController(this, {
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 creating the editable controller or
24provide a complete fallback shape and call `form.update(...)` when data arrives.
25β
26## A field value is `unknown`
27β
28Field names and values are inferred from `defaultValues`. Check that the
29initial object has not been widened to `Record<string, unknown>`, `any`, or an
30unrelated union. Prefer a concrete value type:
31β
32```ts
33type Profile = { firstName: string; age: number }
34β
35const defaults: Profile = { firstName: '', age: 0 }
36const form = new TanStackFormController(this, { defaultValues: defaults })
37```
38β
39For large forms, split rendering into functions typed with `LitFormType`, use a
40scoped `form.formGroup(...)`, or build reusable virtual field bundles with
41`getFieldGroupHelpers()` instead of casting each field value.
42β
43## Form state changed but the template did not update
44β
45Render field state inside `form.field(...)` and selected form state inside
46`form.subscribe(...)`. These Lit directives update only their own child parts.
47Reading `form.api.state` directly in `render()` does not subscribe that markup
48to later changes.
49β
50```ts
51this.form.subscribe(
52 (state) => state.isSubmitting,
53 (isSubmitting) => html` <button ?disabled=${isSubmitting}>Submit</button> `,
54)
55```
56β
57Both directives must be interpolated into a Lit child part. They cannot be used
58as attribute directives.
59β
60## Type instantiation is excessively deep
61β
62This TypeScript error usually involves a very large recursive value shape, a
63widely inferred union, or an unsupported generic wrapper. Reduce it to the
64smallest form that reproduces the problem, keep `defaultValues` concrete, and
65avoid unnecessary generic layers.
66β
67If the minimal reproduction still fails, report it in the
68[TanStack Form issue tracker](https://github.com/TanStack/form/issues). Include
69the TypeScript version, form value type, and smallest failing field.
70β
71## Errors exist but are not displayed
72β
73`field.errors` respects the form's `errorVisibility` policy. Inspect
74`field.meta.original.errors` to determine whether validation ran but the issues
75were intentionally hidden. Confirm that the input calls `field.handleBlur()` if
76the policy depends on `isBlurred`.