Warning Codes

The /api/v1/health endpoint surfaces operator-actionable aggregation anomalies in the top-level warnings array (x-medkit extension). Each entry has the shape:

{
  "code": "leaf_id_collision",
  "message": "Component 'ecu-x' is announced by multiple peers (peer_b, peer_c); routing falls back to last-writer-wins which is non-deterministic. Resolve by renaming the Component on one side or by modelling it as a hierarchical parent (declare a child Component with parentComponentId='ecu-x' on the owning peer).",
  "entity_ids": ["ecu-x"],
  "peer_names": ["peer_b", "peer_c"]
}

Codes are stable machine-readable identifiers: renaming a code is a breaking change for downstream consumers that key on the string.

The canonical list of codes is maintained in src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/warning_codes.hpp; this page mirrors it for API consumers.

Code

Meaning / Remediation

leaf_id_collision

More than one peer announces the same leaf (non-hierarchical) Component ID during aggregation merge. Routing falls back to last-writer-wins, so requests for the affected Component reach one peer non-deterministically. Resolve by renaming the Component on one side, or by modelling it as a hierarchical parent - declare a child Component with parentComponentId pointing at the colliding ID on the owning peer. The warning lists every claiming peer in peer_names.

When aggregation is enabled (GET / -> capabilities.aggregation is true), warnings is always an array on the /health response: empty when no anomalies are active, non-empty otherwise. When aggregation is disabled, the field is omitted entirely.

Schema versioning

Alongside warnings the /health response exposes an integer warning_schema_version (present whenever aggregation is enabled, regardless of whether any warnings are active). Typed clients key on this field to decide which codes they can feature-detect without reverting to string-matching every time a new anomaly class is added.

The contract is:

  • Current version: 1.

  • Bumped by one whenever a code is added, removed, or the shape of a warning object changes.

  • Within a given version, every code listed on this page is guaranteed to appear verbatim; clients seeing an unknown code at a known version should log-and-ignore rather than fail.

  • Across versions, clients are expected to treat unknown codes as future-compatible: log-and-ignore, do not crash.

Clients that need strong typing (MCP tools, Web UI badges, Foxglove panels) should branch on warning_schema_version before mapping codes onto internal enums.