docling-project/docling · error · TypeError

Unsupported label value type

Error message

Unsupported label value type: {type(value)!r}

What it means

Raised as TypeError by HfVisionModelMixin._as_int when the label value is neither an Integral, numpy ndarray, nor torch Tensor. The converter deliberately rejects everything else to avoid silently coercing unexpected label containers.

Solutions

1. Convert to int first: int(round(value)) for float ids, int(label_id) for Python ints.
2. Map class names back to ids using get_label_mapping() before conversion.
3. Convert non-supported arrays to numpy: np.asarray(value).

Example fix

# before
label = model._as_int('Caption')  # str -> TypeError

# after
id2label_inv = {v: k for k, v in model.get_label_mapping().items()}
label = model._as_int(id2label_inv['Caption'])  # int

import numbers
assert isinstance(label, numbers.Integral) or type(label).__module__ in ('numpy', 'torch'), \
    f'label must be an integer id, got {type(label)!r}'

import numbers
import numpy as np

def is_integral_label(value) -> bool:
    if isinstance(value, numbers.Integral):
        return True
    if isinstance(value, np.ndarray):
        return np.issubdtype(value.dtype, np.integer)
    try:
        import torch
        return torch.is_tensor(value) and not torch.is_floating_point(value)
    except ImportError:
        return False

When it happens

Trigger: Passing a Python list, float, string class name, or another array type where an integer class id is expected.

Common situations: Label mappings that emit class-name strings instead of ids; float outputs from a regression head reused as labels; jax/tf arrays from alternative backends.

Related errors

• Expected scalar-like ndarray with size 1, got shape=
• Expected scalar-like tensor with one element, got shape=
• Unsupported score value type
• DOTS JSON parsing requires VlmConvertOptions or…
• Failed to load label mapping from model config at

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

Appendix: source

Thrown at docling/models/inference_engines/common/hf_vision_base.py:156

            return int(value)

        if isinstance(value, np.ndarray):
            if value.size != 1:
                raise TypeError(
                    f"Expected scalar-like ndarray with size 1, got shape={value.shape}"
                )
            return int(value.reshape(-1)[0])

        import torch

        if isinstance(value, torch.Tensor):
            if value.numel() != 1:
                raise TypeError(
                    f"Expected scalar-like tensor with one element, got shape={tuple(value.shape)}"
                )
            return int(value.item())

        raise TypeError(f"Unsupported label value type: {type(value)!r}")

View on GitHub (pinned to 61d76f1ff3)