{"record":{"id":"de5080854c594b73","repo":"huggingface/transformers","slug":"expected-class-name-to-start-with-gemma4-or-gemma3","errorCode":null,"errorMessage":"Expected class name to start with Gemma4 or Gemma3n. Got {self.__class__.__name__}. Gemma4Assistant models require a target model that provides a shared_kv_states dictionary. Currently, only Gemma4 and Gemma3n provide a shared_kv_states dictionary.","messagePattern":"Expected class name to start with Gemma4 or Gemma3n\\. Got (.+?)\\. Gemma4Assistant models require a target model that provides a shared_kv_states dictionary\\. Currently, only Gemma4 and Gemma3n provide a shared_kv_states dictionary\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/generation/utils.py","lineNumber":1049,"sourceCode":"                max_length=generation_config.max_length,\n                logits_processor=logits_processor,\n                vocab_size=self.config.get_text_config().vocab_size,\n            )\n        elif generation_config.use_mtp:\n            candidate_generator = MTPCandidateGenerator(\n                main_model=self,\n                generation_config=generation_config,\n                logits_processor=logits_processor,\n                model_kwargs=model_kwargs,\n            )\n        # SinglePositionMultiTokenCandidateGenerator requires a target model that can provide, and an assistant model that\n        # can work from a shared_kv_states dictionary. Currently, the only models that can provide this are Gemma 3n and\n        # Gemma 4, and the only model that can work from it is a Gemma 4 Assistant\n        elif assistant_model is not None and assistant_model.__class__.__name__.startswith(\n            (\"Gemma4Assistant\", \"Gemma4UnifiedAssistant\")\n        ):\n            if not self.__class__.__name__.startswith((\"Gemma4\", \"Gemma3n\")):\n                raise ValueError(\n                    f\"Expected class name to start with Gemma4 or Gemma3n. Got {self.__class__.__name__}.\"\n                    \" Gemma4Assistant models require a target model that provides a shared_kv_states dictionary.\"\n                    \" Currently, only Gemma4 and Gemma3n provide a shared_kv_states dictionary.\"\n                )\n\n            candidate_generator = SinglePositionMultiTokenCandidateGenerator(\n                input_ids=input_ids,\n                assistant_model=assistant_model,\n                target_model_input_embeddings=self.get_input_embeddings(),\n                generation_config=generation_config,\n                model_kwargs=model_kwargs,\n                inputs_tensor=inputs_tensor,\n                logits_processor=logits_processor,\n            )\n        elif generation_config.speculation_type == \"dflash\":\n            candidate_generator = DFlashTokenCandidateGenerator(\n                assistant_model=assistant_model,\n                main_model_input_embeddings=self.get_input_embeddings(),","sourceCodeStart":1031,"sourceCodeEnd":1067,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/generation/utils.py#L1031-L1067","documentation":"ValueError in candidate-generator selection: you attached a Gemma4Assistant/Gemma4UnifiedAssistant as the assistant model, which consumes a shared_kv_states dictionary produced by the target model. Only target models whose class names start with Gemma4 or Gemma3n expose shared_kv_states, so any other target is rejected up front rather than failing mid-decode with a KeyError.","triggerScenarios":"model.generate(..., assistant_model=gemma4_assistant) where model is e.g. LlamaForCausalLM or any non-Gemma4/Gemma3n decoder; mixing checkpoints when experimenting with MTP-style speculative decoding.","commonSituations":"Trying to graft a Gemma4 assistant onto a different-architecture target for speed; wrappers that rename classes (custom subclass of Gemma4 whose name no longer starts with 'Gemma4').","solutions":["Use a Gemma4 or Gemma3n target model with the Gemma4Assistant.","Or use a target-matched assistant (same architecture family) via the normal AssistantCandidateGenerator path.","If you wrapped Gemma4 in a custom class, ensure inspect-compatible class naming or bypass the SinglePosition path explicitly."],"exampleFix":"# before\nout = llama_model.generate(**inputs, assistant_model=gemma4_assistant)  # raises\n\n# after\nout = gemma4_model.generate(**inputs, assistant_model=gemma4_assistant)","handlingStrategy":"validation","validationCode":"target_ok = model.__class__.__name__.startswith((\"Gemma4\", \"Gemma3n\"))\nassistant_is_g4 = assistant_model.__class__.__name__.startswith((\"Gemma4Assistant\", \"Gemma4UnifiedAssistant\"))\nif assistant_is_g4 and not target_ok:\n    raise ValueError(\"Gemma4Assistant requires a Gemma4/Gemma3n target model\")","typeGuard":"def is_compatible_gemma_pair(target, assistant) -> bool:\n    a = assistant.__class__.__name__.startswith((\"Gemma4Assistant\", \"Gemma4UnifiedAssistant\"))\n    t = target.__class__.__name__.startswith((\"Gemma4\", \"Gemma3n\"))\n    return (not a) or t","tryCatchPattern":null,"preventionTips":["Pair assistants only with target models from the same architecture family.","Avoid renaming/subclassing Gemma model classes in ways that break the name-prefix check.","Validate the target/assistant combination in a startup check for speculative-decoding services."],"tags":["generate","assisted-generation","gemma","model-compatibility","mtp"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}