{"record":{"id":"3489c4c4f2a216f4","repo":"docling-project/docling","slug":"picture-description-batch-size-must-be-1","errorCode":null,"errorMessage":"Picture description batch_size must be >= 1","messagePattern":"Picture description batch_size must be >= 1","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/picture_description_base_model.py","lineNumber":47,"sourceCode":"_USAGE_META_FIELD_NAME = \"usage\"\n\n\nclass PictureDescriptionBaseModel(\n    BaseItemAndImageEnrichmentModel, BaseModelWithOptions\n):\n    images_scale: float = 2.0\n\n    def __init__(\n        self,\n        *,\n        enabled: bool,\n        enable_remote_services: bool,\n        artifacts_path: Optional[Union[Path, str]],\n        options: PictureDescriptionBaseOptions,\n        accelerator_options: AcceleratorOptions,\n    ):\n        if options.batch_size < 1:\n            raise ValueError(\"Picture description batch_size must be >= 1\")\n        if options.scale <= 0:\n            raise ValueError(\"Picture description scale must be > 0\")\n\n        self.enabled = enabled\n        self.options = options\n        self.provenance = \"not-implemented\"\n        self.elements_batch_size = options.batch_size\n        self.images_scale = options.scale\n\n    def is_processable(self, doc: DoclingDocument, element: NodeItem) -> bool:\n        return self.enabled and isinstance(element, PictureItem)\n\n    def _annotate_images(\n        self, images: Iterable[Image.Image]\n    ) -> Iterable[str | ApiImageRequestResult]:\n        raise NotImplementedError\n\n    def __call__(","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/picture_description_base_model.py#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set batch_size to 1 (sequential) or higher (e.g. 2-8 for GPU throughput)","To skip picture description entirely, pass enabled=False instead of batch_size=0","Validate numeric config inputs before constructing pipeline options"],"exampleFix":"# before\noptions = PictureDescriptionBaseOptions(batch_size=0)  # ValueError\n\n# after\n# disable the stage:\nmodel = PictureDescriptionApiModel(enabled=False, options=PictureDescriptionBaseOptions(), ...)\n# or batch sequentially:\noptions = PictureDescriptionBaseOptions(batch_size=1)","handlingStrategy":"validation","validationCode":"from docling.datamodel.picture_description_base_options import PictureDescriptionBaseOptions\n\nbatch_size = int(config.get('batch_size', 2))\nif batch_size < 1:\n    raise SystemExit(f'picture_description batch_size must be >= 1, got {batch_size}')\noptions = PictureDescriptionBaseOptions(batch_size=batch_size)","typeGuard":null,"tryCatchPattern":"try:\n    model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)\nexcept ValueError as e:\n    if 'batch_size' in str(e):\n        options.batch_size = 1  # recover to sequential\n        model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)\n    else:\n        raise","preventionTips":["Validate user-supplied batch_size (>=1) before constructing pipeline options","Use enabled=False to turn picture description off — never batch_size=0","Keep PictureDescription options construction behind a small builder that clamps invalid numerics"],"tags":["picture-description","configuration","validation","batch-size"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}