{"record":{"id":"0cea9499bfee8c66","repo":"huggingface/transformers","slug":"axis-key-for-hqq-backend-has-to-be-one-of-0","errorCode":null,"errorMessage":"`axis_key` for `HQQ` backend has to be one of [`0`, `1`] but got {self.axis_key}","messagePattern":"`axis_key` for `HQQ` backend has to be one of \\[`0`, `1`\\] but got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/cache_utils.py","lineNumber":858,"sourceCode":"            axis_key=axis_key,\n            axis_value=axis_value,\n            q_group_size=q_group_size,\n            residual_length=residual_length,\n        )\n\n        if not is_hqq_available():\n            raise ImportError(\n                \"You need to install `HQQ` in order to use KV cache quantization with HQQ backend. \"\n                \"Please install it via  with `pip install hqq`\"\n            )\n\n        if self.nbits not in [1, 2, 3, 4, 8]:\n            raise ValueError(\n                f\"`nbits` for `HQQ` backend has to be one of [`1`, `2`, `3`, `4`, `8`] but got {self.nbits}\"\n            )\n\n        if self.axis_key not in [0, 1]:\n            raise ValueError(f\"`axis_key` for `HQQ` backend has to be one of [`0`, `1`] but got {self.axis_key}\")\n\n        if self.axis_value not in [0, 1]:\n            raise ValueError(f\"`axis_value` for `HQQ` backend has to be one of [`0`, `1`] but got {self.axis_value}\")\n\n        self.quantizer = HQQQuantizer\n\n    def _quantize(self, tensor, axis):\n        qtensor, meta = self.quantizer.quantize(\n            tensor,\n            axis=axis,\n            device=self.keys.device,\n            compute_dtype=self.keys.dtype,\n            nbits=self.nbits,\n            group_size=self.q_group_size,\n        )\n        meta[\"compute_dtype\"] = self.keys.dtype\n        self.quantizer.cuda(qtensor, meta=meta, device=self.keys.device)  # Move to device and cast to dtype\n        meta[\"scale\"] = meta[\"scale\"].to(qtensor.device)","sourceCodeStart":840,"sourceCodeEnd":876,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cache_utils.py#L840-L876","documentation":"ValueError in HqqQuantizedLayer.__init__ validating axis_key for the HQQ backend. HQQ quantizes along axis 0 (rows, i.e. per token group) or axis 1 (channels/heads); -1 and other axes are not supported by HQQ's quantizer and are rejected at layer construction. Note the convention clash with quanto, which accepts {0, -1} — a direct config port between backends triggers this.","triggerScenarios":"HqqQuantizedCacheConfig(axis_key=-1) (a valid quanto axis) with backend='hqq'; axis_key=2; configs migrated from QuantoQuantizedCacheConfig without translating the axis.","commonSituations":"Backend switching without axis translation; docs/examples mixing the two backends' conventions; symmetric copy-paste where axis_value was translated but axis_key was not.","solutions":["Use axis_key in {0, 1} for the HQQ backend","When porting from quanto: quanto -1 (channel) -> HQQ 1; quanto 0 -> HQQ 0","Keep axis_key and axis_value both within {0, 1} for HQQ"],"exampleFix":"# before (ported from quanto)\nconfig = HqqQuantizedCacheConfig(nbits=8, axis_key=-1, backend='hqq')\n\n# after\nconfig = HqqQuantizedCacheConfig(nbits=8, axis_key=1, backend='hqq')","handlingStrategy":"validation","validationCode":"assert config.backend != 'hqq' or config.axis_key in (0, 1), 'HQQ axis_key must be 0 or 1'","typeGuard":"def is_valid_hqq_axis(axis) -> bool:\n    return axis in (0, 1)","tryCatchPattern":null,"preventionTips":["Use the mapping quanto -1 -> HQQ 1 when porting configs","Validate both axes with the backend's allowlist before constructing the cache","Keep backend-specific config builders so axes and nbits are always paired correctly"],"tags":["quantization","kv-cache","config","validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}