docs: add documentation for NG1002

arturovt · kirjs · commit 030422850b60 · 2026-04-10T10:54:41.000+03:00
Adds a documentation page for the NG01002 runtime error thrown by
FormGroup and FormArray when setValue is called with a value that is
missing an entry for one or more registered controls.

The error code is also changed from positive (1002) to negative (-1002)
so that Angular appends a link to the error reference page in dev mode,
consistent with how other documented errors (e.g. NG01101, NG01203) are
handled.
diff --git a/adev/src/content/reference/errors/NG01002.md b/adev/src/content/reference/errors/NG01002.md
@@ -0,0 +1,46 @@
+# Missing Control Value
+
+This error occurs when you call `setValue` on a `FormGroup` or `FormArray` but the value you pass is missing an entry for one of the registered controls.
+
+`setValue` is strict — it expects a value for every control. If you want to update only some controls, use `patchValue` instead.
+
+## Debugging the error
+
+Check which control is named in the error message, then make sure your value object includes it.
+
+A common source of this error is spreading an object that doesn't have all the keys:
+
+```typescript
+const someValue = {first: 'Nancy'}; // 'last' is missing
+
+form.setValue({...someValue}); // throws NG01002
+```
+
+This can happen if `someValue` comes from an API response, a partial state update, or a type that doesn't fully match the form structure. In those cases, either fill in the missing keys explicitly or switch to `patchValue`.
+
+### FormGroup
+
+```typescript
+const form = new FormGroup({
+  first: new FormControl(''),
+  last: new FormControl(''),
+});
+
+// 'last' is not in the value — throws NG01002
+form.setValue({first: 'Nancy'});
+
+// both controls are covered — works fine
+form.setValue({first: 'Nancy', last: 'Drew'});
+```
+
+### FormArray
+
+```typescript
+const formArray = new FormArray([new FormControl(''), new FormControl('')]);
+
+// only one value for two controls — throws NG01002
+formArray.setValue(['Nancy']);
+
+// one value per control — works fine
+formArray.setValue(['Nancy', 'Drew']);
+```
diff --git a/adev/src/content/reference/errors/overview.md b/adev/src/content/reference/errors/overview.md
@@ -36,6 +36,7 @@
 | `NG0951`  | [Child query result is required but no value is available](errors/NG0951)            |
 | `NG0955`  | [Track expression resulted in duplicated keys for a given collection](errors/NG0955) |
 | `NG0956`  | [Tracking expression caused re-creation of the DOM structure](errors/NG0956)         |
+| `NG01002` | [Missing Control Value](errors/NG01002)                                              |
 | `NG01101` | [Wrong Async Validator Return Type](errors/NG01101)                                  |
 | `NG01203` | [Missing value accessor](errors/NG01203)                                             |
 | `NG02200` | [Missing Iterable Differ](errors/NG02200)                                            |
diff --git a/goldens/public-api/forms/errors.api.md b/goldens/public-api/forms/errors.api.md
@@ -21,7 +21,7 @@ export const enum RuntimeErrorCode {
     // (undocumented)
     MISSING_CONTROL = 1001,
     // (undocumented)
-    MISSING_CONTROL_VALUE = 1002,
+    MISSING_CONTROL_VALUE = -1002,
     // (undocumented)
     NAME_AND_FORM_CONTROL_NAME_MUST_MATCH = 1202,
     // (undocumented)
diff --git a/packages/forms/src/errors.ts b/packages/forms/src/errors.ts
@@ -14,7 +14,7 @@ export const enum RuntimeErrorCode {
   // Structure validation errors (10xx)
   NO_CONTROLS = 1000,
   MISSING_CONTROL = 1001,
-  MISSING_CONTROL_VALUE = 1002,
+  MISSING_CONTROL_VALUE = -1002,
 
   // Reactive Forms errors (1050-1099)
   FORM_CONTROL_NAME_MISSING_PARENT = 1050,
