docling-project/docling · error · ValueError

Cannot specify both code_formula_preset and…

Error message

Cannot specify both code_formula_preset and code_formula_custom_config.

What it means

A Pydantic model validator on the service conversion options rejects configurations that set both code_formula_preset and code_formula_custom_config. These two fields are the preset-based and fully-custom ways to configure the code/formula stage, and they are mutually exclusive by design. The error is raised at model validation time, so it fires as soon as the options object is constructed.

Solutions

Pick one approach: delete code_formula_custom_config and keep the preset, or delete code_formula_preset and keep the custom config.
If you only need small tweaks on top of a preset, check whether the preset id plus per-field overrides elsewhere are enough instead of a full custom config.
Audit your payload builder / template for code that merges default keys so both fields never co-occur.

Example fix

# before
opts = ConvertOptions(
    code_formula_preset="accurate",
    code_formula_custom_config={"some": "tweak"},
)

# after
opts = ConvertOptions(
    code_formula_preset="accurate",
)

Defensive patterns

Strategy: validation

Validate before calling

def assert_code_formula(opts: dict) -> None:
    assert not (opts.get("code_formula_preset") and opts.get("code_formula_custom_config")), (
        "code_formula_preset and code_formula_custom_config are mutually exclusive"
    )

Try / catch

try:
    opts = ConvertOptions(**payload)
except ValidationError as e:
    if "code_formula_preset" in str(e):
        payload.pop("code_formula_custom_config", None)
        opts = ConvertOptions(**payload)
    else:
        raise

Prevention

Model configs with exactly one of preset/custom_config per stage at the type level (a union type).
Build payloads through a helper that refuses to set both fields.

When it happens

Trigger: Constructing the service request options with both code_formula_preset (a string preset id) and code_formula_custom_config (a dict/model) set, e.g. options = ServiceOptions(code_formula_preset='accurate', code_formula_custom_config={...}). Any payload sent to the service that includes both keys fails validation with this message.

Common situations: Copy-pasting a config snippet that already had a preset and then adding custom tweaks on top; migrating from presets to custom config without removing the old key; JSON payloads where a default preset is merged in by a template system.

Related errors

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

Appendix: source

Thrown at docling/datamodel/service/options.py:1070

        )

        if legacy_set and new_set:
            raise ValueError(
                "Cannot mix legacy picture description options (picture_description_local/api) "
                "with new options (picture_description_preset/custom_config). "
                "Please use only one approach."
            )

        # Note: Deprecation warnings are now emitted by field validators
        # when the fields are set, not here in the model validator

        return self

    @model_validator(mode="after")
    def validate_code_formula_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for code/formula."""
        if self.code_formula_preset and self.code_formula_custom_config:
            raise ValueError(
                "Cannot specify both code_formula_preset and code_formula_custom_config."
            )

        return self

    @model_validator(mode="after")
    def validate_layout_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for layout."""
        if self.layout_preset and self.layout_custom_config:
            raise ValueError(
                "Cannot specify both layout_preset and layout_custom_config."
            )
        return self

    @model_validator(mode="after")
    def validate_picture_classification_options(self) -> Self:
        """Ensure preset and custom config are mutually exclusive for picture classification."""
        if (

View on GitHub (pinned to 61d76f1ff3)