{"record":{"id":"1d3a4b3596bf8535","repo":"docling-project/docling","slug":"picture-description-scale-must-be-0","errorCode":null,"errorMessage":"Picture description scale must be > 0","messagePattern":"Picture description scale must be > 0","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/picture_description_base_model.py","lineNumber":49,"sourceCode":"\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__(\n        self,\n        doc: DoclingDocument,","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/picture_description_base_model.py#L31-L67","documentation":"PictureDescriptionModel validates at construction that options.scale is strictly positive: scale multiplies the rendered image resolution when cropping pictures for description (default 2.0). Zero or negative scale is rejected with this ValueError because it would yield empty or nonsensical images.","triggerScenarios":"Instantiating a picture description model with PictureDescriptionBaseOptions(scale=0) or a negative number — e.g. misreading scale as a percentage (0.2 for 20%) or passing a fraction meant for downscaling.","commonSituations":"Confusing scale (a multiplier, default 2.0) with a 0-1 fraction; config typos; programmatically computed scale values that can hit 0 for tiny pictures.","solutions":["Use a positive multiplier such as the default 2.0 (render at 2x page resolution), or 1.0 for native resolution","If you meant to reduce cost, lower scale toward 1.0 or disable the stage with enabled=False — never 0","Sanity-check computed scale values (scale = max(scale, 1.0)) before building options"],"exampleFix":"# before\noptions = PictureDescriptionBaseOptions(scale=0)  # ValueError\n\n# after\noptions = PictureDescriptionBaseOptions(scale=2.0)  # default: 2x resolution crops","handlingStrategy":"validation","validationCode":"from docling.datamodel.picture_description_base_options import PictureDescriptionBaseOptions\n\nscale = float(config.get('scale', 2.0))\nif scale <= 0:\n    raise SystemExit(f'picture_description scale must be > 0, got {scale}')\noptions = PictureDescriptionBaseOptions(scale=scale)","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 'scale' in str(e):\n        options.scale = 2.0  # fall back to default\n        model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)\n    else:\n        raise","preventionTips":["Remember scale is a multiplier (default 2.0), not a 0-1 fraction","Validate scale > 0 in config parsing before building the pipeline","Document that disabling the stage uses enabled=False, not zeroed numeric options"],"tags":["picture-description","configuration","validation","image-scale"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}