Skip to content

Commit 600da64

Browse files
surajy93amishne
authored andcommitted
docs(forms): add NG01902 error reference and link to docs
Add the NG01902 (Orphan field in signal forms) documentation page to the Error Encyclopedia and change the ORPHAN_FIELD_PROPERTY error code to -1902 so Angular's RuntimeError automatically appends a link to angular.dev/errors/NG01902 in the thrown error message. (cherry picked from commit f2c6445)
1 parent a40e2ce commit 600da64

3 files changed

Lines changed: 28 additions & 1 deletion

File tree

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Orphan field in signal forms
2+
3+
This error indicates that a `Field` instance is no longer connected to the current model structure.
4+
Angular signal forms throw `NG01902` when a field path that previously existed can no longer be resolved as the same property in the parent object.
5+
6+
A common trigger is unintentionally setting a field's value to `undefined`.
7+
In signal forms, `undefined` means "field does not exist", so an existing field can become orphaned.
8+
9+
## Why this happens
10+
11+
Signal forms keep field instances in sync with your model shape.
12+
If code still references an older field instance after the model shape changed, Angular detects the mismatch and throws this error.
13+
14+
This can happen when:
15+
16+
- a property is removed from the model object
17+
- a property becomes `undefined` instead of remaining present
18+
- code holds a stale field reference across structural updates
19+
20+
## How to fix it
21+
22+
- Avoid writing `undefined` to model fields. Use `null` or another explicit value when the field should still exist.
23+
- Keep the model shape stable while a field is in use.
24+
- Re-read fields from the current form tree after structural updates instead of reusing stale references.
25+
26+
For model design guidance, see [Avoid `undefined`](/guide/forms/signals/model-design#avoid-undefined).

adev/src/content/reference/errors/overview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
| `NG01002` | [Missing Control Value](errors/NG01002) |
4040
| `NG01101` | [Wrong Async Validator Return Type](errors/NG01101) |
4141
| `NG01203` | [Missing value accessor](errors/NG01203) |
42+
| `NG01902` | [Orphan field in signal forms](errors/NG01902) |
4243
| `NG02200` | [Missing Iterable Differ](errors/NG02200) |
4344
| `NG02800` | [JSONP support in HttpClient configuration](errors/NG02800) |
4445
| `NG02802` | [Headers not transferred by HttpTransferCache](errors/NG02802) |

packages/forms/signals/src/errors.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ export const enum RuntimeErrorCode {
1414
// Signal Forms errors (1900-1999)
1515
PATH_NOT_IN_FIELD_TREE = 1900,
1616
PATH_RESOLUTION_FAILED = 1901,
17-
ORPHAN_FIELD_PROPERTY = 1902,
17+
ORPHAN_FIELD_PROPERTY = -1902,
1818
ORPHAN_FIELD_ARRAY = 1903,
1919
ORPHAN_FIELD_NOT_FOUND = 1904,
2020
ROOT_FIELD_NO_PARENT = 1905,

0 commit comments

Comments
 (0)