Error reference

A2UI validation errors and how to fix them

Use stable subcodes and JSON Pointers to locate a failing A2UI v0.9.1 value, understand the cause, and compare it with a payload that passes.

Tested against a2ui-v0.9.1-basic@3f6877b · Last verified July 16, 2026

Read the result

From broad code to exact value

Every actionable result contains a broad error code, a stable subcode, message index, and JSON Pointer. The pointer locates the failing value; copied reports never need to expose the original payload.

Quick reference

Eight reproducible A2UI validation errors

Each row links to a broken payload that is covered by an automated validator test.

Subcode	Top-level code	JSON Pointer
`PARSE_ERROR`	`INVALID_JSON_OR_JSONL`	`/`
`VERSION_NOT_V091`	`UNSUPPORTED_VERSION`	`/version`
`AJV_TYPE`	`SCHEMA_MISMATCH`	`/updateComponents/components/1/text`
`SURFACE_NOT_CREATED`	`INVALID_SURFACE_OR_COMPONENT_GRAPH`	`/updateComponents/surfaceId`
`ROOT_MISSING`	`INVALID_SURFACE_OR_COMPONENT_GRAPH`	`/updateComponents/components`
`DUPLICATE_COMPONENT_ID`	`INVALID_SURFACE_OR_COMPONENT_GRAPH`	`/updateComponents/components/1/id`
`UNKNOWN_COMPONENT_REFERENCE`	`INVALID_SURFACE_OR_COMPONENT_GRAPH`	`/updateComponents/components/0/children/0`
`COMPONENT_CYCLE`	`INVALID_SURFACE_OR_COMPONENT_GRAPH`	`/updateComponents/components/0/children/0`

Error 1

The JSON or JSONL cannot be parsed

INVALID_JSON_OR_JSONLPARSE_ERROR

CauseThe input ends before the createSurface object is complete.

FixClose the object and provide both surfaceId and the official Basic Catalog ID.

Pointer/

Broken payload

{"version":"v0.9.1","createSurface":{

Tested fix

{
  "version": "v0.9.1",
  "createSurface": {
    "surfaceId": "parse-fixed",
    "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
  }
}

Error 2

The message uses a different A2UI version

UNSUPPORTED_VERSIONVERSION_NOT_V091

CauseThe validator is intentionally pinned to exact v0.9.1 messages.

FixSet version to v0.9.1 on every message in the stream.

Pointer/version

Broken payload

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "version-fix",
    "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
  }
}

Tested fix

{
  "version": "v0.9.1",
  "createSurface": {
    "surfaceId": "version-fix",
    "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
  }
}

Error 3

A component property has the wrong type

SCHEMA_MISMATCHAJV_TYPE

CauseThe Text component receives a number where the Basic Catalog schema expects text.

FixReplace the numeric text value with a string.

Pointer/updateComponents/components/1/text

Broken payload

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "type-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "type-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "title"
          ]
        },
        {
          "id": "title",
          "component": "Text",
          "text": 42
        }
      ]
    }
  }
]

Tested fix

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "type-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "type-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "title"
          ]
        },
        {
          "id": "title",
          "component": "Text",
          "text": "Hello"
        }
      ]
    }
  }
]

Error 4

The surface is updated before it is created

INVALID_SURFACE_OR_COMPONENT_GRAPHSURFACE_NOT_CREATED

CauseThe stream starts with updateComponents for a surface that has no active createSurface message.

FixSend createSurface first with the same surfaceId. Re-create a surface before updating it after deletion.

Pointer/updateComponents/surfaceId

Broken payload

[
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "missing-surface",
      "components": [
        {
          "id": "root",
          "component": "Text",
          "text": "Hello"
        }
      ]
    }
  }
]

Tested fix

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "missing-surface",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "missing-surface",
      "components": [
        {
          "id": "root",
          "component": "Text",
          "text": "Hello"
        }
      ]
    }
  }
]

Error 5

The final component graph has no root

INVALID_SURFACE_OR_COMPONENT_GRAPHROOT_MISSING

CauseThe stream defines a title component but never defines the required component with id root.

FixAdd a root component and connect the existing component through a structural reference.

Pointer/updateComponents/components

Broken payload

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "root-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "root-fix",
      "components": [
        {
          "id": "title",
          "component": "Text",
          "text": "Hello"
        }
      ]
    }
  }
]

Tested fix

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "root-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "root-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "title"
          ]
        },
        {
          "id": "title",
          "component": "Text",
          "text": "Hello"
        }
      ]
    }
  }
]

Error 6

Two components use the same ID

INVALID_SURFACE_OR_COMPONENT_GRAPHDUPLICATE_COMPONENT_ID

CauseA single updateComponents message defines root twice.

FixGive every component a unique ID and update structural references to match.

Pointer/updateComponents/components/1/id

Broken payload

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "duplicate-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "duplicate-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": []
        },
        {
          "id": "root",
          "component": "Text",
          "text": "Duplicate"
        }
      ]
    }
  }
]

Tested fix

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "duplicate-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "duplicate-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "note"
          ]
        },
        {
          "id": "note",
          "component": "Text",
          "text": "Unique"
        }
      ]
    }
  }
]

Error 7

A structural reference points to an unknown component

INVALID_SURFACE_OR_COMPONENT_GRAPHUNKNOWN_COMPONENT_REFERENCE

Causeroot lists missing as a child, but the completed stream never defines that component ID.

FixDefine the referenced component in this stream or remove the reference.

Pointer/updateComponents/components/0/children/0

Broken payload

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "reference-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "reference-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "missing"
          ]
        }
      ]
    }
  }
]

Tested fix

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "reference-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "reference-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "missing"
          ]
        },
        {
          "id": "missing",
          "component": "Text",
          "text": "Hello"
        }
      ]
    }
  }
]

Error 8

Component references form a cycle

INVALID_SURFACE_OR_COMPONENT_GRAPHCOMPONENT_CYCLE

Causeroot references branch, and branch points back to root.

FixRemove one structural edge so every component can be reached without returning to an ancestor.

Pointer/updateComponents/components/0/children/0

Broken payload

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "cycle-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "cycle-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "branch"
          ]
        },
        {
          "id": "branch",
          "component": "Column",
          "children": [
            "root"
          ]
        }
      ]
    }
  }
]

Tested fix

[
  {
    "version": "v0.9.1",
    "createSurface": {
      "surfaceId": "cycle-fix",
      "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
    }
  },
  {
    "version": "v0.9.1",
    "updateComponents": {
      "surfaceId": "cycle-fix",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "children": [
            "branch"
          ]
        },
        {
          "id": "branch",
          "component": "Column",
          "children": []
        }
      ]
    }
  }
]

Check the complete stream

Verify the repair in A2UI Validator

Paste the complete payload rather than an isolated update. Validation runs locally, and copied reports exclude the original JSON or JSONL.

Open A2UI Validator Copy known-valid A2UI examples

A2UI validation errors and how to fix them

From broad code to exact value

Eight reproducible A2UI validation errors

The JSON or JSONL cannot be parsed

The message uses a different A2UI version

A component property has the wrong type

The surface is updated before it is created

The final component graph has no root

Two components use the same ID

A structural reference points to an unknown component

Component references form a cycle

Verify the repair in A2UI Validator

Continue debugging with the source model