docling-project/docling · error · ValueError

MLX models do not support HuggingFace StoppingCriteria insta

Error message

MLX models do not support HuggingFace StoppingCriteria instances. Found {type(criteria).__name__}. Use GenerationStopper instead.

What it means

MLX generation has no hook for HF's transformers.StoppingCriteria objects. MlxVlmModel validates vlm_options.custom_stopping_criteria at init and raises ValueError if any entry is an instance of StoppingCriteria, telling you to use Docling's GenerationStopper callables instead.

Source

Thrown at docling/models/vlm_pipeline_models/mlx_model.py:102

                    f"Model '{self.vlm_options.repo_id}' not found in artifacts_path.\n"
                    f"Expected location: {artifacts_path / repo_cache_folder}\n"
                    f"Available models in {artifacts_path}: "
                    f"{', '.join(available_models) if available_models else 'none'}\n\n"
                    f"To fix this issue:\n"
                    f"  1. Download the model: docling-tools models download-hf-repo {self.vlm_options.repo_id}\n"
                    f"  2. Or remove --artifacts-path to enable auto-download\n"
                    f"  3. Or use a different model that exists in your artifacts_path"
                )

            ## Load the model
            self.vlm_model, self.processor = load(artifacts_path)
            self.config = load_config(artifacts_path)

            # Validate custom stopping criteria - MLX doesn't support HF StoppingCriteria
            if self.vlm_options.custom_stopping_criteria:
                for criteria in self.vlm_options.custom_stopping_criteria:
                    if isinstance(criteria, StoppingCriteria):
                        raise ValueError(
                            f"MLX models do not support HuggingFace StoppingCriteria instances. "
                            f"Found {type(criteria).__name__}. Use GenerationStopper instead."
                        )
                    elif isinstance(criteria, type) and issubclass(
                        criteria, StoppingCriteria
                    ):
                        raise ValueError(
                            f"MLX models do not support HuggingFace StoppingCriteria classes. "
                            f"Found {criteria.__name__}. Use GenerationStopper instead."
                        )

    def __call__(
        self, conv_res: ConversionResult, page_batch: Iterable[Page]
    ) -> Iterable[Page]:
        page_list = list(page_batch)
        if not page_list:
            return

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Replace the StoppingCriteria instance with an equivalent GenerationStopper-based stopper
2. Keep HF StoppingCriteria only for pipelines running the Transformers/vLLM engines
3. Wrap your stop predicate in a GenerationStopper-compatible callable before assigning it

Example fix

# before
from transformers import StoppingCriteria
class MyStop(StoppingCriteria): ...
vlm_options.custom_stopping_criteria = [MyStop()]
# after
from docling.models.base_vlm_model import GenerationStopper
class MyStopper(GenerationStopper): ...
vlm_options.custom_stopping_criteria = [MyStopper()]

from transformers import StoppingCriteria

for c in vlm_options.custom_stopping_criteria or []:
    if isinstance(c, StoppingCriteria):
        raise ValueError(f'{type(c).__name__} is HF StoppingCriteria; convert to GenerationStopper for MLX')

from docling.models.base_vlm_model import GenerationStopper

def is_mlx_safe_criteria(c) -> bool:
    return isinstance(c, GenerationStopper) or (callable(c) and not isinstance(c, type))

try:
    model = MlxVlmModel(...)
except ValueError as e:
    if 'StoppingCriteria instances' in str(e):
        vlm_options.custom_stopping_criteria = [to_generation_stopper(c) for c in vlm_options.custom_stopping_criteria]
        model = MlxVlmModel(...)
    else:
        raise

When it happens

Trigger: Assigning vlm_options.custom_stopping_criteria = [MyStoppingCriteria()] (a transformers.StoppingCriteria subclass instance) and constructing the MLX model; typical when porting a Transformers-engine config to MLX unchanged.

Common situations: Copying HF examples that define StoppingCriteria subclasses for length/keyword stopping; shared option presets reused across Transformers and MLX pipelines.

Related errors

• Expected MlxVlmEngineOptions, got {type(options)}
• Model not loaded. Ensure EngineModelConfig was provided duri
• MLX models do not support HuggingFace StoppingCriteria class
• Unsupported VLM inference framework: {vlm_options.inference_
• {p} does not exist or is not a directory containing the requ

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