Repository navigation
Closed
Labels
triageissues that need triageissues that need triage
Description
Where you use Phoenix
Self-hosted (phoenix-client library; verified against the client payload and the server's annotation schema).
Version
packages/phoenix-client on main at a73b42b (2026-10-30), Python 3.12.2, Windows 11.
What happened?
client.spans.log_span_annotations_dataframe() skips the required-column validation that its document sibling performs, so two common misuses produce confusing failures instead of the clear ValueError the document methods give.
- Missing
annotator_kindcolumn and no globalannotator_kind. The request body carries"annotator_kind": null, which the server rejects (422,annotations.pyrequires the Literal). The document method raises:
ValueError: DataFrame must contain columns: {'annotator_kind'}. Found columns: [...] - Missing
name/annotation_namecolumn and no globalannotation_name. The span method raises the opaqueValueError: 'Error processing row 0: '; the document method raises:
ValueError: DataFrame must contain either 'name' or 'annotation_name' column when annotation_name_required=True
Expected: the span DataFrame methods validate the same required columns (and raise the same clear errors) as the document methods before building the request.
Reproduction
from phoenix.client import Client
client = Client(base_url="http://localhost:6006")
# (a) no annotator_kind column, no global value
client.spans.log_span_annotations_dataframe(df) # -> payload annotator_kind=None -> server 422
# (c) no name/annotation_name column, no global value
client.spans.log_span_annotations_dataframe(df2) # -> ValueError: 'Error processing row 0: 'Actual output:
--- (a) span annotations, no annotator_kind column, no global value ---
request payload: {'name': 'sentiment', 'annotator_kind': None, 'span_id': 'span-1', 'result': {'label': 'positive'}}
--- (b) document sibling, same situation (clear ValueError) ---
document error: ValueError DataFrame must contain columns: {'annotator_kind'}. Found columns: ['span_id', 'document_position', 'name', 'label']
--- (c) span annotations, no name column, no global annotation_name ---
span error: ValueError 'Error processing row 0: '
--- (d) document sibling, no name column (clear ValueError) ---
document error: ValueError "DataFrame must contain either 'name' or 'annotation_name' column when annotation_name_required=True"
The script is self-contained (no server needed; it inspects the built payload and the raised errors); happy to attach it.
Additional information
- The document path passes
annotation_name_required/annotator_kind_requiredinto its validation (packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py:1401-1405sync,:2727-2731async); the span DataFrame path at:1027/:2328does not. - Server-side requirement:
src/phoenix/server/api/routers/v1/annotations.py:64(annotator_kind: AnnotatorKind). - Related precedent: [BUG]: Document annotation dataframe validation skips document_position type checks #13771 fixed a missing
document_positiontype check in the document path; this is the analogous gap on the span path. - Searched open and closed issues/PRs for span annotation DataFrame validation and
annotator_kind: no duplicate.
Reacted by dosubot
Metadata
Metadata
Assignees
Labels
triageissues that need triageissues that need triage
Type
Projects
- StatusShow more project fields✅ Done
Activity