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

What it means

After fetching model metadata from the KServe v2 server, the engine found zero input tensors. The engine needs at least one named input to send pixel values to, so an empty inputs list means the server returned metadata without inputs — typically a wrong model served at the endpoint, a routing/version mismatch, or a non-conforming server.

Source

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

                "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]:
        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"

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Verify the served model actually exposes inputs: query the server's ModelReady and ModelMetadata endpoints directly with the same model_name/model_version.
2. Check options.model_name and options.model_version match the deployed model exactly (the default derives a name from the HF repo id with '/' replaced by '--').
3. Wait until the InferenceService reports READY before initializing the engine.
4. If the server is custom, ensure its metadata response includes the inputs field per the KServe v2 protocol.

Example fix

# before: wrong model name resolves to metadata-less endpoint
options.model_name = "my-model"

# after: verify metadata before initializing the engine
meta = client.get_model_metadata()
assert meta.inputs, f"server returned {len(meta.inputs)} inputs"
engine.initialize()

meta = kserve_client.get_model_metadata()
if not meta.inputs:
    raise ValueError(
        f"model '{model_name}' metadata has no inputs; is the endpoint/model_name correct?"
    )

try:
    engine.initialize()
except RuntimeError as e:
    if "at least 1 input" in str(e):
        # endpoint/model mismatch — check model_name/model_version, then re-init once
        options.model_name = correct_name
        engine = ApiKserveV2ImageClassificationEngine(...)
        engine.initialize()
    else:
        raise

When it happens

Trigger: ApiKserveV2ImageClassificationEngine.initialize() -> _resolve_tensor_names() when client.get_model_metadata() returns a metadata object whose inputs list is empty (model_metadata.inputs == []).

Common situations: Pointing inference_url at a model-ready but metadata-incomplete server; KServe InferenceService still loading (model not ready) so metadata omits inputs; wrong model_name or model_version resolving to a different model; predictor/transformer graph exposing only outputs.

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/e1e247e822ec3b81. Report an issue: GitHub.