docling-project/docling · error · RuntimeError

Expected image-classification model metadata to expose at le

Error message

Expected image-classification model metadata to expose at least 1 output, got {len(metadata.outputs)} outputs.

What it means

The KServe v2 model metadata response contains no output tensors. The engine reads outputs[0].name to know which tensor holds the logits, so zero outputs makes inference impossible. This signals a metadata/endpoint mismatch rather than a client bug.

Source

Thrown at docling/models/inference_engines/image_classification/api_kserve_v2_engine.py:81

            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]:
        if self._kserve_client is None:
            raise RuntimeError("KServe v2 client is not initialized.")

        metadata = self._kserve_client.get_model_metadata()
        if not metadata.inputs:
            raise RuntimeError(
                f"Expected image-classification model metadata to expose at least 1 input, "
                f"got {len(metadata.inputs)} inputs."
            )
        if not metadata.outputs:
            raise RuntimeError(
                f"Expected image-classification model metadata to expose at least 1 output, "
                f"got {len(metadata.outputs)} outputs."
            )

        input_name = metadata.inputs[0].name
        output_name = metadata.outputs[0].name
        return input_name, output_name

    def initialize(self) -> None:
        """Initialize preprocessor/labels and prepare remote client."""
        _log.info("Initializing KServe v2 image-classification engine")

        revision = self._model_config.revision or "main"
        model_folder = self._resolve_model_folder(
            repo_id=self._repo_id, revision=revision
        )

        self._processor = self._load_preprocessor(model_folder)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Inspect the server's ModelMetadata response directly and confirm it declares at least one output tensor.
2. Correct options.model_name / options.model_version to point at the actual image-classification model.
3. Ensure the InferenceService is fully READY before engine initialization.
4. Fix the custom server to include outputs in its metadata response.

Example fix

# before
options.model_version = None  # resolves to wrong/default version

# after: pin the version whose metadata exposes outputs
options.model_version = "v1"
meta = client.get_model_metadata()
assert meta.outputs, "no outputs in model metadata"

meta = kserve_client.get_model_metadata()
if not meta.outputs:
    raise ValueError(
        f"model '{model_name}' metadata has no outputs; wrong model or not READY?"
    )

try:
    engine.initialize()
except RuntimeError as e:
    if "at least 1 output" in str(e):
        options.model_version = pinned_version
        engine = ApiKserveV2ImageClassificationEngine(...)
        engine.initialize()
    else:
        raise

When it happens

Trigger: ApiKserveV2ImageClassificationEngine.initialize() -> _resolve_tensor_names() when get_model_metadata() returns an outputs list that is empty (model_metadata.outputs == []).

Common situations: Endpoint serves a different model kind (e.g. a transformer-only stage); model still loading so metadata is incomplete; wrong model_name/model_version; custom server not implementing the v2 metadata contract fully.

Related errors

• Expected image-classification model metadata to expose at le
• Invalid metadata response from {self.model_metadata_url}: {e
• Invalid BYTES data: insufficient bytes for string of length
• Connections to remote services are only allowed when set exp
• Missing expected KServe v2 output: {self._output_name}

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