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 2 inputs (images, orig_target_sizes), got {len(metadata.inputs)}.

What it means

After querying the KServe v2 server's model metadata, the engine requires at least 2 input tensors (images, orig_target_sizes), matching the RT-DETR-style object detection contract. If the served model exposes fewer than 2 inputs, a RuntimeError is raised because the engine cannot map its preprocessed inputs onto the model graph.

Source

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

                "pipeline_options.enable_remote_services=True."
            )

    def _resolve_model_name(self) -> str:
        if self.options.model_name:
            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,

View on GitHub (pinned to 61d76f1ff3)

Solutions

Verify the endpoint actually serves an RT-DETR-style detector with 'images' and 'orig_target_sizes' inputs (inspect with a direct KServe metadata REST/gRPC call).
Fix the model_name / url in ApiKserveV2ObjectDetectionEngineOptions to point at the correct object-detection model.
If you control the server, correct its model repository config so both inputs are exposed.

Defensive patterns

Strategy: try-catch

Validate before calling

# probe the endpoint before wiring it into docling
from docling.clients.kserve_client import KserveV2Client
c = KserveV2Client(url=opts.url, inference_port=opts.inference_port)
meta = c.get_model_metadata()
assert len(meta.inputs) >= 2, f"need images+orig_target_sizes inputs, got {[i.name for i in meta.inputs]}"

Try / catch

try:
    engine.initialize()
except RuntimeError as e:
    if "at least 2 inputs" in str(e):
        raise RuntimeError(f"Endpoint {opts.url} does not serve a DETR-style detector") from e
    raise

Prevention

Smoke-test the KServe endpoint's metadata before configuring Docling against it.
Pin model_name/model_version so the served model cannot drift.
Serve RT-DETR exports that keep the standard images/orig_target_sizes inputs.

When it happens

Trigger: Pointing ApiKserveV2ObjectDetectionEngineOptions.url at a KServe v2 endpoint that serves a model other than an RT-DETR/DETR-family object detector — e.g. a classifier, a segmentation model, or a text model — so get_model_metadata() returns 0 or 1 inputs.

Common situations: Reusing a KServe endpoint previously set up for a different task; serving the wrong model revision or a base (non-finetuned) checkpoint; a Triton/KServe model repository with a misconfigured config.pbtxt that renamed or hid inputs.

Related errors

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