docling-project/docling · error · ValueError

Picture description scale must be > 0

Error message

Picture description scale must be > 0

What it means

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.

Source

Thrown at docling/models/picture_description_base_model.py:49

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__(
        self,
        doc: DoclingDocument,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use a positive multiplier such as the default 2.0 (render at 2x page resolution), or 1.0 for native resolution
2. If you meant to reduce cost, lower scale toward 1.0 or disable the stage with enabled=False — never 0
3. Sanity-check computed scale values (scale = max(scale, 1.0)) before building options

Example fix

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

# after
options = PictureDescriptionBaseOptions(scale=2.0)  # default: 2x resolution crops

from docling.datamodel.picture_description_base_options import PictureDescriptionBaseOptions

scale = float(config.get('scale', 2.0))
if scale <= 0:
    raise SystemExit(f'picture_description scale must be > 0, got {scale}')
options = PictureDescriptionBaseOptions(scale=scale)

try:
    model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)
except ValueError as e:
    if 'scale' in str(e):
        options.scale = 2.0  # fall back to default
        model = PictureDescriptionApiModel(enabled=True, enable_remote_services=False, artifacts_path=None, options=options, accelerator_options=acc)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Picture description batch_size must be >= 1
• 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/1d3a4b3596bf8535. Report an issue: GitHub.