{"record":{"id":"f789d17c1152a4ad","repo":"docling-project/docling","slug":"mlx-models-do-not-support-huggingface-stoppingcrit-f789d1","errorCode":null,"errorMessage":"MLX models do not support HuggingFace StoppingCriteria classes. Found {criteria.__name__}. Use GenerationStopper instead.","messagePattern":"MLX models do not support HuggingFace StoppingCriteria classes\\. Found (.+?)\\. Use GenerationStopper instead\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/mlx_model.py","lineNumber":109,"sourceCode":"                    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\n        valid_pages = []\n        invalid_pages = []\n\n        for page in page_list:\n            assert page._backend is not None\n            if not page._backend.is_valid():\n                invalid_pages.append(page)","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/mlx_model.py#L91-L127","documentation":"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.","triggerScenarios":"Passing an uninstantiated StoppingCriteria subclass in vlm_options.custom_stopping_criteria (e.g. [MyStop] instead of [MyStop()]) when initializing the MLX model.","commonSituations":"Copying engine-agnostic config that stores classes to defer instantiation; shared option presets reused across Transformers and MLX pipelines.","solutions":["Instantiate GenerationStopper subclasses and pass instances rather than classes","Register MLX-incompatible stoppers only for non-MLX pipelines; keep a per-engine criteria list","If a callable stop predicate exists, adapt it to the GenerationStopper protocol"],"exampleFix":"# before\nvlm_options.custom_stopping_criteria = [MyHFStop]  # class, subclasses StoppingCriteria\n# after\nvlm_options.custom_stopping_criteria = [MyGenerationStopper()]  # instance, MLX-compatible","handlingStrategy":"type-guard","validationCode":"from transformers import StoppingCriteria\n\nfor c in vlm_options.custom_stopping_criteria or []:\n    if isinstance(c, type) and issubclass(c, StoppingCriteria):\n        raise ValueError(f'{c.__name__} is an HF StoppingCriteria class; instantiate a GenerationStopper instead')","typeGuard":"from transformers import StoppingCriteria\n\ndef is_mlx_safe_criteria_entry(c) -> bool:\n    if isinstance(c, type):\n        return not issubclass(c, StoppingCriteria)\n    return not isinstance(c, StoppingCriteria)","tryCatchPattern":"try:\n    model = MlxVlmModel(...)\nexcept ValueError as e:\n    if 'StoppingCriteria classes' in str(e):\n        vlm_options.custom_stopping_criteria = [c() if isinstance(c, type) else c for c in vlm_options.custom_stopping_criteria]\n        model = MlxVlmModel(...)\n    else:\n        raise","preventionTips":["Never pass uninstantiated classes into shared option objects","Document the GenerationStopper protocol next to your stopper implementations","Validate criteria entries once at config-load time"],"tags":["mlx","stopping-criteria","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}