ERROR REFERENCE
Common A2UI stream errors.
Most A2UI failures are not ordinary JSON syntax errors. They occur when individually readable messages contradict protocol state or build an incomplete component graph. Use this reference to interpret the validator’s semantic findings.
UNKNOWN_SURFACE
An update or deletion references a surfaceId that has not been created, or that was already deleted. Send createSurface first. In an orchestrated system, also confirm that the agent owns the surface and that transport ordering was preserved.
DUPLICATE_SURFACE
The stream creates an active surface twice. A surface’s ID and catalog are fixed for its lifetime. Delete it before recreating it, or choose a new globally unique ID.
MESSAGE_ENVELOPE
The object contains no recognized message key or more than one. Split combined operations into separate JSONL messages. Keep protocol metadata outside the envelope unless the transport specification provides a dedicated location.
DUPLICATE_COMPONENT
The same component ID appears twice in one updateComponents batch. Across separate updates, the same ID can be an intentional upsert. Within one list it is ambiguous and commonly indicates an LLM copied a component while editing.
MISSING_ROOT
The accumulated surface has components but no component whose ID is root. v0.9 uses that conventional ID as the graph entry point. Rename the intended top-level container or add a small root container that references the visible children.
MISSING_CHILD
A static child ID remains unresolved after the entire pasted stream. Forward references are legal during progressive rendering, so this is reported only after processing all messages. Check spelling, truncation and whether the missing component was sent to another surface.
COMPONENT_CYCLE
Following child links returns to an ancestor. A renderer cannot turn that adjacency list into a finite UI tree. Break the cycle and represent repeated data through bindings or catalog-supported templates rather than parent-child recursion.
UNREACHABLE_COMPONENT
A component exists but cannot be reached from root. This is a warning because an incremental stream may intentionally stage nodes, but stale unreachable nodes increase payload size and often reveal a missed child link.
JSON_POINTER
A data-model path does not begin with /. A2UI uses JSON Pointer-style paths. Use /user/name, not user.name or user/name. Remember that literal ~ and / inside pointer tokens require RFC 6901 escaping.