{"record":{"id":"ee92b44f8a2562f4","repo":"docling-project/docling","slug":"mlx-models-do-not-support-huggingface-stoppingcrit","errorCode":null,"errorMessage":"MLX models do not support HuggingFace StoppingCriteria instances. Found {type(criteria).__name__}. Use GenerationStopper instead.","messagePattern":"MLX models do not support HuggingFace StoppingCriteria instances\\. Found (.+?)\\. Use GenerationStopper instead\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/mlx_model.py","lineNumber":102,"sourceCode":"                    f\"Model '{self.vlm_options.repo_id}' not found in artifacts_path.\\n\"\n                    f\"Expected location: {artifacts_path / repo_cache_folder}\\n\"\n                    f\"Available models in {artifacts_path}: \"\n                    f\"{', '.join(available_models) if available_models else 'none'}\\n\\n\"\n                    f\"To fix this issue:\\n\"\n                    f\"  1. Download the model: docling-tools models download-hf-repo {self.vlm_options.repo_id}\\n\"\n                    f\"  2. Or remove --artifacts-path to enable auto-download\\n\"\n                    f\"  3. Or use a different model that exists in your artifacts_path\"\n                )\n\n            ## Load the model\n            self.vlm_model, self.processor = load(artifacts_path)\n            self.config = load_config(artifacts_path)\n\n            # Validate custom stopping criteria - MLX doesn't support HF StoppingCriteria\n            if self.vlm_options.custom_stopping_criteria:\n                for criteria in self.vlm_options.custom_stopping_criteria:\n                    if isinstance(criteria, StoppingCriteria):\n                        raise ValueError(\n                            f\"MLX models do not support HuggingFace StoppingCriteria instances. \"\n                            f\"Found {type(criteria).__name__}. Use GenerationStopper instead.\"\n                        )\n                    elif isinstance(criteria, type) and issubclass(\n                        criteria, StoppingCriteria\n                    ):\n                        raise ValueError(\n                            f\"MLX models do not support HuggingFace StoppingCriteria classes. \"\n                            f\"Found {criteria.__name__}. Use GenerationStopper instead.\"\n                        )\n\n    def __call__(\n        self, conv_res: ConversionResult, page_batch: Iterable[Page]\n    ) -> Iterable[Page]:\n        page_list = list(page_batch)\n        if not page_list:\n            return\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/mlx_model.py#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"Copying HF examples that define StoppingCriteria subclasses for length/keyword stopping; shared option presets reused across Transformers and MLX pipelines.","solutions":["Replace the StoppingCriteria instance with an equivalent GenerationStopper-based stopper","Keep HF StoppingCriteria only for pipelines running the Transformers/vLLM engines","Wrap your stop predicate in a GenerationStopper-compatible callable before assigning it"],"exampleFix":"# before\nfrom transformers import StoppingCriteria\nclass MyStop(StoppingCriteria): ...\nvlm_options.custom_stopping_criteria = [MyStop()]\n# after\nfrom docling.models.base_vlm_model import GenerationStopper\nclass MyStopper(GenerationStopper): ...\nvlm_options.custom_stopping_criteria = [MyStopper()]","handlingStrategy":"type-guard","validationCode":"from transformers import StoppingCriteria\n\nfor c in vlm_options.custom_stopping_criteria or []:\n    if isinstance(c, StoppingCriteria):\n        raise ValueError(f'{type(c).__name__} is HF StoppingCriteria; convert to GenerationStopper for MLX')","typeGuard":"from docling.models.base_vlm_model import GenerationStopper\n\ndef is_mlx_safe_criteria(c) -> bool:\n    return isinstance(c, GenerationStopper) or (callable(c) and not isinstance(c, type))","tryCatchPattern":"try:\n    model = MlxVlmModel(...)\nexcept ValueError as e:\n    if 'StoppingCriteria instances' in str(e):\n        vlm_options.custom_stopping_criteria = [to_generation_stopper(c) for c in vlm_options.custom_stopping_criteria]\n        model = MlxVlmModel(...)\n    else:\n        raise","preventionTips":["Store stopping criteria per engine in your config, not one shared list","Standardize on GenerationStopper across all engines","Add an init-time validation pass over vlm_options before building any model"],"tags":["mlx","stopping-criteria","configuration","vlm"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}