docling-project/docling · error · ValueError

Unknown prompt style: {prompt_style}. Valid values are {', '

Error message

Unknown prompt style: {prompt_style}. Valid values are {', '.join(s.value for s in TransformersPromptStyle)}

What it means

The VLM prompt-formatting helper builds prompts according to a TransformersPromptStyle enum. Reaching the else branch — a value not matching any known style — raises ValueError listing the valid enum values. With a well-typed enum this is nearly unreachable, so it usually indicates a version skew or a raw string being passed where the enum is expected.

Source

Thrown at docling/models/inference_engines/vlm/_utils.py:192

        formatted = (
            f"{user_prompt_prefix}<|image_1|>{prompt}{prompt_suffix}{assistant_prompt}"
        )
        _log.debug(f"Formatted prompt for {repo_id}: {formatted}")
        return formatted
    elif prompt_style == TransformersPromptStyle.CHAT:
        # Standard chat template with image placeholder
        messages = [
            {
                "role": "user",
                "content": [
                    {"type": "image"},
                    {"type": "text", "text": prompt},
                ],
            }
        ]
        return processor.apply_chat_template(messages, add_generation_prompt=True)
    else:
        raise ValueError(
            f"Unknown prompt style: {prompt_style}. "
            f"Valid values are {', '.join(s.value for s in TransformersPromptStyle)}"
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Always pass a TransformersPromptStyle enum member (e.g. TransformersPromptStyle.CHAT_TEMPLATE) rather than a raw string.
When loading config, coerce explicitly: TransformersPromptStyle(raw_value) inside a try to fail early with a clear message.
Align docling and docling-core versions if new enum values are involved.

Example fix

# before
engine_options.prompt_style = "chat"  # not a valid enum value

# after
from docling.datamodel.vlm_model_specs import TransformersPromptStyle  # (module per installed version)
engine_options.prompt_style = TransformersPromptStyle.CHAT_TEMPLATE

Defensive patterns

Strategy: validation

Validate before calling

valid = {s.value for s in TransformersPromptStyle}
if prompt_style not in valid:
    raise ValueError(f"prompt_style must be one of {valid}, got {prompt_style!r}")

Type guard

def is_prompt_style(v: object) -> "TypeGuard[TransformersPromptStyle]":
    return isinstance(v, TransformersPromptStyle)

Try / catch

try:
    prompt = format_prompt_for_vlm(processor, prompt, style)
except ValueError as e:
    raise ValueError(f"Bad prompt_style in config; valid: {[s.value for s in TransformersPromptStyle]}") from e

Prevention

Pass enum members, not strings, for prompt_style.
Coerce and validate deserialized config values to the enum at load time.
Keep docling/docling-core versions aligned when new enum members appear.

When it happens

Trigger: Passing a prompt_style that is a plain string or an enum member from a different/older docling-core version whose values no longer match, into the VLM engine options used by format_prompt_for_vlm.

Common situations: Deserializing options from YAML/JSON where prompt_style stays a str instead of being coerced to TransformersPromptStyle; mixed docling/docling-core versions after a partial upgrade; user code constructing lookalike enums.

Related errors

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