docling-project/docling · error · RuntimeError

Expected object-detection model metadata to expose at least

Error message

Expected object-detection model metadata to expose at least 3 outputs (labels, boxes, scores), got {len(metadata.outputs)}.

What it means

The KServe v2 engine requires the served model's metadata to expose at least 3 output tensors (labels, boxes, scores) in the DETR output convention. Fewer outputs means the served model is not a compatible object detector, and the engine raises RuntimeError rather than guessing which outputs to read.

Source

Thrown at docling/models/inference_engines/object_detection/api_kserve_v2_engine.py:85

            return self.options.model_name

        return self._repo_id.replace("/", "--")

    def _resolve_model_version(self) -> Optional[str]:
        return self.options.model_version

    def _resolve_tensor_names(self) -> tuple[str, str, str, str, str]:
        if self._kserve_client is None:
            raise RuntimeError("KServe v2 client is not initialized.")

        metadata = self._kserve_client.get_model_metadata()
        if len(metadata.inputs) < 2:
            raise RuntimeError(
                "Expected object-detection model metadata to expose at least 2 inputs "
                f"(images, orig_target_sizes), got {len(metadata.inputs)}."
            )
        if len(metadata.outputs) < 3:
            raise RuntimeError(
                "Expected object-detection model metadata to expose at least 3 outputs "
                f"(labels, boxes, scores), got {len(metadata.outputs)}."
            )

        input_images_name = metadata.inputs[0].name
        input_orig_target_sizes_name = metadata.inputs[1].name
        output_labels_name = metadata.outputs[0].name
        output_boxes_name = metadata.outputs[1].name
        output_scores_name = metadata.outputs[2].name

        return (
            input_images_name,
            input_orig_target_sizes_name,
            output_labels_name,
            output_boxes_name,
            output_scores_name,
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Confirm the served model is an RT-DETR/DETR-family export producing labels, boxes and scores outputs; check with a raw KServe v2 metadata request.
Re-export the model with the standard 3-tensor detection head, or point options.model_name at the correct model.
Match the model revision configured on the server to the one Docling's model spec expects.

Defensive patterns

Strategy: try-catch

Validate before calling

meta = KserveV2Client(url=opts.url).get_model_metadata()
assert len(meta.outputs) >= 3, f"need labels/boxes/scores outputs, got {[o.name for o in meta.outputs]}"

Try / catch

try:
    engine.initialize()
except RuntimeError as e:
    if "at least 3 outputs" in str(e):
        raise RuntimeError("Served model is not a DETR-family detector; fix the KServe model repo") from e
    raise

Prevention

Validate server metadata (inputs>=2, outputs>=3) in deployment smoke tests.
Keep the served export and Docling's expected RT-DETR contract in sync.
Alert on server-side model redeployments that change the graph.

When it happens

Trigger: The KServe v2 endpoint's get_model_metadata() reports fewer than 3 outputs — e.g. a classifier returning a single logits tensor, or a detection model exported with fused/renamed outputs.

Common situations: Serving a model exported with the wrong ONNX opset/export config that collapsed outputs; pointing at the wrong model name on a multi-model server; version skew between the exported model and what the engine expects.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/25dd35b4b072db9c. Report an issue: GitHub.