roboflow/supervision · error · ValueError

Malformed CreateML annotation entry {annotation}: {exc}

Error message

Malformed CreateML annotation entry {annotation}: {exc}

What it means

Raised by createml_annotations_to_detections when an annotation lacks required fields — coordinates, or any of x/y/width/height inside coordinates, or label — or when values cannot be converted (TypeError on non-numeric strings). It wraps KeyError/TypeError from the field extraction with the full annotation echoed.

Source

Thrown at src/supervision/dataset/formats/createml.py:113

        array([0])

        ```
    """
    if not image_annotations:
        return Detections.empty()

    xyxy = []
    class_ids = []
    for annotation in image_annotations:
        try:
            coordinates = annotation["coordinates"]
            x_center = float(coordinates["x"])
            y_center = float(coordinates["y"])
            width = float(coordinates["width"])
            height = float(coordinates["height"])
            label = annotation["label"]
        except (KeyError, TypeError) as exc:
            raise ValueError(
                f"Malformed CreateML annotation entry {annotation!r}: {exc}"
            ) from exc
        xyxy.append(
            [
                x_center - width / 2,
                y_center - height / 2,
                x_center + width / 2,
                y_center + height / 2,
            ]
        )
        class_ids.append(class_to_index[label])

    return Detections(
        xyxy=np.array(xyxy, dtype=np.float32),
        class_id=np.array(class_ids, dtype=int),
    )

View on GitHub (pinned to 7f254d9784)

Solutions

  1. Ensure every annotation has label plus coordinates with numeric x, y, width, height.
  2. Convert CreateML-incompatible schemas before loading (e.g. compute width/height from x1/y1/x2/y2: x=(x1+x2)/2, width=x2-x1).
  3. Pre-scan and drop/repair malformed annotations before calling the loader.

Example fix

// before
{"label": "dog", "coordinates": {"x": 50, "y": 50}}

// after
{"label": "dog", "coordinates": {"x": 50, "y": 50, "width": 20, "height": 20}}
Defensive patterns

Strategy: validation

Validate before calling

def is_valid_createml_annotation(ann: object) -> bool:
    """Check the full CreateML annotation shape before loading."""
    if not isinstance(ann, dict):
        return False
    coords = ann.get("coordinates")
    if not isinstance(coords, dict):
        return False
    try:
        float(coords["x"]), float(coords["y"]), float(coords["width"]), float(coords["height"])
    except (KeyError, TypeError, ValueError):
        return False
    return isinstance(ann.get("label"), str)

Type guard

def createml_entry_is_well_formed(entry: dict) -> bool:
    """True when all annotations in the entry pass shape validation."""
    return all(is_valid_createml_annotation(a) for a in (entry.get("annotations") or []))

Try / catch

try:
    sv.DetectionDataset.from_createml(images_directory_path=d, annotations_path=a)
except ValueError as exc:
    if "Malformed CreateML annotation entry" in str(exc):
        bad = [a for e in json.load(open(a)) for a in (e.get('annotations') or []) if not is_valid_createml_annotation(a)]
        raise ValueError(f"Repair {len(bad)} malformed annotations") from exc
    raise

Prevention

When it happens

Trigger: An annotation dict missing "coordinates", or coordinates missing one of "x"/"y"/"width"/"height" (e.g. only x/y present with no size), or "label" absent, during load_createml_annotations.

Common situations: Annotations from a keypoint or polygon-oriented tool that writes different coordinate fields; partially written files; coordinates written as nested strings ('{"x": ...}') instead of numbers.

Understand the failure class

Related errors

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/979b331ef18080fa. Report an issue: GitHub.