{"record":{"id":"4e7815d15957eab5","repo":"unslothai/unsloth","slug":"apply-chat-template-returned-none-tokenizer-may","errorCode":null,"errorMessage":"apply_chat_template returned None — tokenizer may be incompatible","messagePattern":"apply_chat_template returned None — tokenizer may be incompatible","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/mlx_inference.py","lineNumber":1541,"sourceCode":"        from mlx_lm.sample_utils import make_sampler, make_logits_processors\n\n        from core.inference.chat_template_helpers import (\n            apply_chat_template_for_generation,\n            detect_think_prefill,\n            render_with_native_template_fallback,\n        )\n\n        prompt = apply_chat_template_for_generation(\n            self._tokenizer,\n            messages,\n            tools = tools,\n            enable_thinking = enable_thinking,\n            reasoning_effort = reasoning_effort,\n            preserve_thinking = preserve_thinking,\n            continue_final_message = continue_final_message,\n        )\n        if prompt is None:\n            raise RuntimeError(\"apply_chat_template returned None — tokenizer may be incompatible\")\n\n        # Parity with the transformers backend: if the template dropped the\n        # requested tools, fall back to the native template so MLX text models\n        # keep advertising them. self._tokenizer is this entry's tokenizer, so\n        # probe and native render share a renderer. (VLM renders via the\n        # processor for image tokens and is not wired here.)\n        model_info = self.models.get(self.active_model_name, {})\n        render_result = render_with_native_template_fallback(\n            formatted_prompt = prompt,\n            tokenizer = self._tokenizer,\n            model_info = model_info,\n            active_model_name = self.active_model_name,\n            messages = messages,\n            tools = tools,\n            enable_thinking = enable_thinking,\n            reasoning_effort = reasoning_effort,\n            preserve_thinking = preserve_thinking,\n            continue_final_message = continue_final_message,","sourceCodeStart":1523,"sourceCodeEnd":1559,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/mlx_inference.py#L1523-L1559","documentation":"Raised when apply_chat_template_for_generation returns None for the MLX tokenizer path. Unlike an empty string (which template fallbacks may repair), None means the renderer outright failed — typically because the tokenizer has no usable chat template or is incompatible with the message/kwargs combination (tools, enable_thinking, reasoning_effort, continue_final_message). The backend treats None as fatal with this RuntimeError hinting at tokenizer incompatibility.","triggerScenarios":"Text-model generation where apply_chat_template returns None: missing chat_template in tokenizer_config.json, a template that raises on tool/thinking kwargs and the wrapper converts that to None, or a tokenizer from a different model family than the weights.","commonSituations":"Base models without chat templates; sending tools=... to a model whose template predates tool-calling syntax; mismatched tokenizer/model after manual conversions.","solutions":["Use a chat/instruct checkpoint with a complete chat_template that supports the features you pass (tools, thinking).","Drop the advanced kwargs (tools, enable_thinking, reasoning_effort, continue_final_message) and retry — if it renders, the template simply lacks those extensions.","Verify tokenizer/model provenance match; re-download the repo if tokenizer assets are suspect."],"exampleFix":"# before\nprompt = apply_chat_template_for_generation(tokenizer, messages,\n    tools=tools, enable_thinking=True)  # returns None -> RuntimeError\n\n# after\nprompt = apply_chat_template_for_generation(tokenizer, messages)  # template lacks tool/thinking support","handlingStrategy":"fallback","validationCode":"probe = apply_chat_template_for_generation(tokenizer, [{'role': 'user', 'content': 'hi'}])\nif probe is None:\n    raise ValueError('tokenizer cannot render chat; dropping advanced kwargs or using a chat model required')","typeGuard":null,"tryCatchPattern":"try:\n    prompt = apply_chat_template_for_generation(tokenizer, messages,\n        tools=tools, enable_thinking=enable_thinking)\nexcept RuntimeError as e:\n    if 'returned None' in str(e) and tools is not None:\n        prompt = apply_chat_template_for_generation(tokenizer, messages)  # retry without tools\n    else:\n        raise","preventionTips":["Probe template capability (tools/thinking) at load time and strip unsupported kwargs per model.","Use instruct checkpoints with complete templates for tool/thinking workflows.","Distinguish None (fatal) from '' (repairable via native fallback) in template handling code."],"tags":["mlx","chat-template","tokenizer","inference"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}