docling-project/docling · error · ValueError

Cannot specify both chunking_preset and chunking_options.

Error message

Cannot specify both chunking_preset and chunking_options.

What it means

The validate_chunking_options model validator rejects options that set both chunking_preset and chunking_options. Chunking is configured either by a named preset or by an explicit options object, never both. The check uses `is not None` against chunking_options, so any non-None chunking_options together with a truthy preset raises.

Source

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

            warnings.warn(
                "ocr_engine is deprecated and will be removed in a future version. "
                "Use ocr_preset instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            # Sync ocr_engine value to ocr_preset only if ocr_preset wasn't explicitly set
            object.__setattr__(self, "ocr_preset", self.ocr_engine)

        # Ensure preset and custom_config are mutually exclusive
        if self.ocr_preset != "auto" and self.ocr_custom_config:
            raise ValueError("Cannot specify both ocr_preset and ocr_custom_config.")

        return self

    @model_validator(mode="after")
    def validate_chunking_options(self) -> Self:
        if self.chunking_preset and self.chunking_options is not None:
            raise ValueError(
                "Cannot specify both chunking_preset and chunking_options."
            )

        return self

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Keep exactly one: chunking_preset for a named configuration, chunking_options for explicit control.
2. If you set chunking_options to the preset's defaults and tweaked one field, remove the preset and keep only chunking_options.
3. Grep your config/JSON for both keys appearing in the same section.

Example fix

# before
opts = ConvertOptions(
    chunking_preset="aggressive",
    chunking_options=HybridChunkerOptions(merge_peers=True),
)

# after
opts = ConvertOptions(
    chunking_options=HybridChunkerOptions(merge_peers=True),
)

def assert_chunking(opts: dict) -> None:
    assert not (opts.get("chunking_preset") and opts.get("chunking_options") is not None), (
        "chunking_preset and chunking_options are mutually exclusive"
    )

try:
    ConvertOptions(**cfg)
except ValidationError as e:
    if "chunking" in str(e):
        raise ValueError("Set only chunking_preset or chunking_options, not both") from e
    raise

When it happens

Trigger: Constructing options with chunking_preset='aggressive' and chunking_options=HybridChunkerOptions(...) (or a dict) at the same time, e.g. in a service request payload or the SDK options model.

Common situations: Taking a preset from documentation and adding explicit chunking parameters for RAG tuning; config files where chunking_options was set previously and a chunking_preset line was appended later; forgetting that the preset already encapsulates chunker settings.

Related errors

• Cannot specify both code_formula_preset and code_formula_cus
• Cannot specify both layout_preset and layout_custom_config.
• Cannot specify both picture_classification_preset and pictur
• Cannot specify both ocr_preset and ocr_custom_config.
• Invalid device option. Use `auto`, `cpu`, `mps`, `xpu`, `cud

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