Failures and diagnostics

Let lifecycle and Pydantic errors surface at their natural boundary:

Error	Meaning
UnsetError	A draft field was read before it had a usable value
DraftError	A draft was copied or sent through Pydantic serialization, or a final was finalized again
TemplateError	An unbound template was used as though it had validated field values
Pydantic ValidationError	Final input, interpolation output, or a structural Config position was invalid
TypeError	A Config class disabled a lifecycle invariant or declared an unsupported schema shape
AttributeError	A draft write used an unknown field or interpolation read unavailable context

Missing draft values

Required scalar reads fail immediately. Required direct Config fields create a child draft, but a recursive required spine without a base case fails rather than recursing forever. Pending interpolation can be assigned and finalized but cannot be read from a draft.

Interpolation failures

Interpolation errors report the target path and callable site. Common causes are:

• reading a later field;

• selecting an ancestor above the current root;

• requesting the wrong typed context model;

• returning an active incomplete branch;

• mutating a read-only built-in container view;

• raising inside the user callable.

Reorder source fields before dependent fields. For a default child that needs parent context, use the direct child: Child = Child() spelling. The standalone child constructor becomes an unbound template and binds in the parent’s field pipeline. Do not use a draft-returning default factory.

An unbound template is created only by normal Config(...) construction when at least one interpolation lacks an ancestor/root/nearest context or raises NameError, with no other errors except omitted required fields. A repeated NameError during binding is reported as a normal interpolation failure. Other Pydantic validation entry points never return templates.

Structural graph failures

Draft collection and template binding follow concrete annotations through Config fields and supported built-in containers. A Config under Any, object, a wrong union branch, or an incompatible tuple or mapping position is rejected. Markers inside built-in containers are also rejected.

Arbitrary user objects are opaque and are not crawled for drafts or markers. If such an object needs lifecycle-aware children, move those children into directly annotated Config fields.

Native Pydantic footguns

model_copy(update=...) does not validate updates. Model-after validators and model_post_init may mutate values after interpolation. Shallowly frozen finals may still have mutable container contents. Revalidate current concrete values with type(final).model_validate(final) when needed.