docling-project/docling · error · ValueError

MLX models do not support HuggingFace StoppingCriteria class

Error message

MLX models do not support HuggingFace StoppingCriteria classes. Found {criteria.__name__}. Use GenerationStopper instead.

What it means

Companion guard to the instance check: if an entry of vlm_options.custom_stopping_criteria is a class (not an instance) that subclasses transformers.StoppingCriteria, MlxVlmModel raises ValueError, since MLX cannot consume HF stopping-criteria classes any more than instances. Use GenerationStopper instead.

Source

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

                    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

        valid_pages = []
        invalid_pages = []

        for page in page_list:
            assert page._backend is not None
            if not page._backend.is_valid():
                invalid_pages.append(page)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Instantiate GenerationStopper subclasses and pass instances rather than classes
2. Register MLX-incompatible stoppers only for non-MLX pipelines; keep a per-engine criteria list
3. If a callable stop predicate exists, adapt it to the GenerationStopper protocol

Example fix

# before
vlm_options.custom_stopping_criteria = [MyHFStop]  # class, subclasses StoppingCriteria
# after
vlm_options.custom_stopping_criteria = [MyGenerationStopper()]  # instance, MLX-compatible

from transformers import StoppingCriteria

for c in vlm_options.custom_stopping_criteria or []:
    if isinstance(c, type) and issubclass(c, StoppingCriteria):
        raise ValueError(f'{c.__name__} is an HF StoppingCriteria class; instantiate a GenerationStopper instead')

from transformers import StoppingCriteria

def is_mlx_safe_criteria_entry(c) -> bool:
    if isinstance(c, type):
        return not issubclass(c, StoppingCriteria)
    return not isinstance(c, StoppingCriteria)

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

When it happens

Trigger: Passing an uninstantiated StoppingCriteria subclass in vlm_options.custom_stopping_criteria (e.g. [MyStop] instead of [MyStop()]) when initializing the MLX model.

Common situations: Copying engine-agnostic config that stores classes to defer instantiation; shared option presets reused across Transformers and MLX pipelines.

Related errors

• MLX models do not support HuggingFace StoppingCriteria insta
• Expected MlxVlmEngineOptions, got {type(options)}
• Model not loaded. Ensure EngineModelConfig was provided duri
• Unknown EBCDIC codec {encoding!r}.
• The EBCDIC backend needs a layout: set either EbcdicBackendO

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