docling-project/docling · error · RuntimeError

The specified picture description kind is not supported: {pi

Error message

The specified picture description kind is not supported: {pipeline_options.picture_description_options.kind}.

What it means

During pipeline initialization, _get_picture_description_model(artifacts_path) returns None when picture_description_options.kind does not match any supported backend (the registry of picture description models has no entry for that kind string). Because the model is unconditionally assigned (even when picture description is disabled), an unknown kind aborts pipeline construction with RuntimeError.

Source

Thrown at docling/pipeline/base_pipeline.py:169

        super().__init__(pipeline_options)
        self.pipeline_options: ConvertPipelineOptions

        # We need picture classification to do chart_extraction
        # Use local variable to avoid mutating shared pipeline_options
        do_picture_classification = (
            pipeline_options.do_picture_classification
            or pipeline_options.do_chart_extraction
        )

        # ------ Common enrichment models working on all backends

        # Picture description model
        if (
            picture_description_model := self._get_picture_description_model(
                artifacts_path=self.artifacts_path
            )
        ) is None:
            raise RuntimeError(
                f"The specified picture description kind is not supported: {pipeline_options.picture_description_options.kind}."
            )

        self.enrichment_pipe = [
            # Document Picture Classifier
            DocumentPictureClassifier(
                enabled=do_picture_classification,
                artifacts_path=self.artifacts_path,
                options=pipeline_options.picture_classification_options,
                accelerator_options=pipeline_options.accelerator_options,
                enable_remote_services=pipeline_options.enable_remote_services,
            ),
            # Document Picture description
            picture_description_model,
        ]

        # Lazily import torch-backed chart extraction only when enabled so
        # docling-slim / ONNX-only installs can import DocumentConverter without

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set picture_description_options.kind to a supported value — check PictureDescriptionOptions/defaults via PdfPipelineOptions().picture_description_options and the models registry in this docling version
2. After upgrading, rebuild options from the current version's defaults instead of reusing serialized options
3. If you do not need picture descriptions, leave picture_description_options at its default rather than a hand-written kind string

Example fix

# before
opts.picture_description_options = PictureDescriptionApiOptions(kind='smoldocling')  # unknown kind

# after
opts.picture_description_options.kind = 'SMOLDOCLING_SERVICE'  # a kind registered in this version

kind = opts.picture_description_options.kind
# introspect the supported kinds registered in this docling version
from docling.models.picture_description_model import PictureDescriptionModel  # module path may vary; check registry
supported = set(PictureDescriptionModel.get_models().keys()) if hasattr(PictureDescriptionModel, 'get_models') else None
if supported is not None and kind not in supported:
    raise ValueError(f'kind {kind!r} not in {sorted(supported)}')

When it happens

Trigger: Setting PdfPipelineOptions(do_picture_description=True/False) with picture_description_options=PictureDescriptionApiOptions or a custom options object whose kind is not in the supported set (e.g. a typo like 'smolvlm' vs 'SMOLDOCLING_SERVICE' or an API kind used where a local model is required). Also triggered by carrying an options object from an older docling version whose kinds were removed/renamed.

Common situations: Upgrading docling and reusing persisted pipeline options; enabling picture enrichment with a kind string from docs of a different version; API-description options used while enable_remote_services=False or artifacts_path forces local models.

Related errors

• Picture description batch_size must be >= 1
• Picture description scale must be > 0
• Unknown EBCDIC codec {encoding!r}.
• The EBCDIC backend needs a layout: set either EbcdicBackendO
• Could not read the EBCDIC layout {self.options.layout_file}.

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