{"record":{"id":"3e5abc21331a0bb4","repo":"vllm-project/vllm","slug":"could-not-uniquely-identify-the-extract-hidden-sta","errorCode":null,"errorMessage":"Could not uniquely identify the extract-hidden-states KV cache group among {len(groups)} groups; the hidden-states layer must be isolated in its own group (MLA verifiers are unsupported).","messagePattern":"Could not uniquely identify the extract-hidden-states KV cache group among (.+?) groups; the hidden-states layer must be isolated in its own group \\(MLA verifiers are unsupported\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/example_hidden_states_connector.py","lineNumber":133,"sourceCode":"\n        Located by spec type so it resolves on both scheduler and worker side.\n        \"\"\"\n        if kv_cache_config is None:\n            return 0\n\n        from vllm.v1.kv_cache_interface import HiddenStateCacheSpec\n\n        groups = kv_cache_config.kv_cache_groups\n        group_ids = [\n            gid\n            for gid, group in enumerate(groups)\n            if isinstance(group.kv_cache_spec, HiddenStateCacheSpec)\n        ]\n        if len(group_ids) == 1:\n            return group_ids[0]\n        if not group_ids and len(groups) == 1:\n            return 0\n        raise ValueError(\n            \"Could not uniquely identify the extract-hidden-states KV cache \"\n            f\"group among {len(groups)} groups; the hidden-states layer must be \"\n            \"isolated in its own group (MLA verifiers are unsupported).\"\n        )\n\n    @staticmethod\n    def _get_cache_block_size(\n        vllm_config: \"VllmConfig\",\n        kv_cache_config: \"KVCacheConfig | None\",\n        cache_kv_group_id: int,\n    ) -> int:\n        \"\"\"Block size of the hidden-states group, read from its own spec.\n\n        cache_config.block_size is bumped to a common multiple for hybrid\n        verifiers; the page-aligned hidden-states group keeps a smaller one.\n        \"\"\"\n        if kv_cache_config is None:\n            return vllm_config.cache_config.block_size","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/example_hidden_states_connector.py#L115-L151","documentation":"The example hidden-states connector must map to the single KV cache group whose spec is HiddenStateCacheSpec (e.g. the extract-hidden-states layer). It scans kv_cache_config.kv_cache_groups; exactly one match is required, or the whole config must consist of one group only (then group 0 is assumed). Otherwise — including any MLA verifier setup — the group is ambiguous and setup aborts.","triggerScenarios":"kv_cache_config contains zero or multiple HiddenStateCacheSpec groups while also having more than one group total; typically MLA models where hidden-states cannot be isolated, or multi-group hybrid configs where the hidden-states spec appears alongside other specs in a way that is not uniquely identifiable.","commonSituations":"Using the hidden-states KV transfer example with an MLA model as verifier (explicitly unsupported); a hybrid model config that splits the hidden-states layer into a shared group with attention layers.","solutions":["Configure the model so the hidden-states layer is isolated in its own KV cache group (own kv_cache_spec/group)","Do not use this connector with MLA verifiers — it is unsupported by design","Simplify to a single kv_cache_group, in which case group 0 is used unconditionally"],"exampleFix":"# before: hidden-states layer shares a group with attention layers -> ambiguous\n# (model config yields groups=[attention+hidden])\n\n# after: isolate the hidden-states layer so groups=[attention, hidden_states]\n# e.g. ensure the extract-hidden-states layer maps to its own FullAttentionSpec/HiddenStateCacheSpec group","handlingStrategy":"validation","validationCode":"from vllm.v1.kv_cache_interface import HiddenStateCacheSpec\ngroups = kv_cache_config.kv_cache_groups\nids = [i for i, g in enumerate(groups) if isinstance(g.kv_cache_spec, HiddenStateCacheSpec)]\nassert len(ids) == 1 or (not ids and len(groups) == 1), \"hidden-states group not unique\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not pair this example connector with MLA verifiers","Structure hybrid models so the hidden-states layer gets its own KV cache group"],"tags":["kv-transfer","hidden-states","kv-cache-groups","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}