docling-project/docling · error · ValueError

Picture description batch_size must be >= 1

Error message

Picture description batch_size must be >= 1

What it means

PictureDescriptionModel (base class for picture-description enrichment in Docling pipelines) validates its options at construction: batch_size must be at least 1. A value of 0 or negative is rejected immediately with this ValueError instead of silently producing no work or division errors later.

Source

Thrown at docling/models/picture_description_base_model.py:47

_USAGE_META_FIELD_NAME = "usage"


class PictureDescriptionBaseModel(
    BaseItemAndImageEnrichmentModel, BaseModelWithOptions
):
    images_scale: float = 2.0

    def __init__(
        self,
        *,
        enabled: bool,
        enable_remote_services: bool,
        artifacts_path: Optional[Union[Path, str]],
        options: PictureDescriptionBaseOptions,
        accelerator_options: AcceleratorOptions,
    ):
        if options.batch_size < 1:
            raise ValueError("Picture description batch_size must be >= 1")
        if options.scale <= 0:
            raise ValueError("Picture description scale must be > 0")

        self.enabled = enabled
        self.options = options
        self.provenance = "not-implemented"
        self.elements_batch_size = options.batch_size
        self.images_scale = options.scale

    def is_processable(self, doc: DoclingDocument, element: NodeItem) -> bool:
        return self.enabled and isinstance(element, PictureItem)

    def _annotate_images(
        self, images: Iterable[Image.Image]
    ) -> Iterable[str | ApiImageRequestResult]:
        raise NotImplementedError

    def __call__(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set batch_size to 1 (sequential) or higher (e.g. 2-8 for GPU throughput)
2. To skip picture description entirely, pass enabled=False instead of batch_size=0
3. Validate numeric config inputs before constructing pipeline options

Example fix

# before
options = PictureDescriptionBaseOptions(batch_size=0)  # ValueError

# after
# disable the stage:
model = PictureDescriptionApiModel(enabled=False, options=PictureDescriptionBaseOptions(), ...)
# or batch sequentially:
options = PictureDescriptionBaseOptions(batch_size=1)

from docling.datamodel.picture_description_base_options import PictureDescriptionBaseOptions

batch_size = int(config.get('batch_size', 2))
if batch_size < 1:
    raise SystemExit(f'picture_description batch_size must be >= 1, got {batch_size}')
options = PictureDescriptionBaseOptions(batch_size=batch_size)

try:
    model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)
except ValueError as e:
    if 'batch_size' in str(e):
        options.batch_size = 1  # recover to sequential
        model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)
    else:
        raise

When it happens

Trigger: Instantiating any picture description model (e.g. PictureDescriptionApiModel or the HF variant) with PictureDescriptionBaseOptions(batch_size=0) or a negative value — commonly when someone tries to 'disable batching' with 0.

Common situations: Setting batch_size=0 intending to disable picture processing (use enabled=False instead); config files generated from user input where 0 passes through unvalidated; env-var-driven configs parsing to 0.

Related errors

• Picture description scale must be > 0
• The parameters picture_description_local and picture_descrip
• Cannot specify both picture_description_preset and picture_d
• Cannot mix legacy picture description options (picture_descr
• Cannot specify both code_formula_preset and code_formula_cus

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