{"record":{"id":"fb56fdf2025174a7","repo":"RyanCodrai/turbovec","slug":"bit-width-must-be-2-3-or-4-got-bit-width","errorCode":null,"errorMessage":"bit_width must be 2, 3, or 4, got {bit_width}","messagePattern":"bit_width must be 2, 3, or 4, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"turbovec-python/python/turbovec/agno.py","lineNumber":190,"sourceCode":"        :param path: Optional directory for save/load persistence. When\n            given to the constructor, :meth:`create` loads existing data\n            from this path if present.\n        \"\"\"\n        super().__init__(\n            id=id,\n            name=name,\n            description=description,\n            similarity_threshold=similarity_threshold,\n        )\n        if embedder is None:\n            raise ValueError(\n                \"`embedder` is required; turbovec needs the embedder's \"\n                \"`dimensions` to size the underlying index.\"\n            )\n        if embedder.dimensions is None:\n            raise ValueError(\"Embedder.dimensions must be set.\")\n        if bit_width not in (2, 3, 4):\n            raise ValueError(f\"bit_width must be 2, 3, or 4, got {bit_width}\")\n        if search_type != SearchType.vector:\n            raise ValueError(\n                f\"TurboQuantVectorDb only supports search_type=SearchType.vector; \"\n                f\"got {search_type}. Use LanceDb / Chroma / etc. for keyword \"\n                f\"or hybrid search.\"\n            )\n        if distance not in (Distance.cosine, Distance.max_inner_product):\n            raise ValueError(\n                f\"TurboQuantVectorDb supports distance=Distance.cosine or \"\n                f\"distance=Distance.max_inner_product; got {distance}. \"\n                f\"L2 distance is not supported by the underlying \"\n                f\"inner-product kernel.\"\n            )\n\n        self.embedder: Embedder = embedder\n        self.dimensions: int = embedder.dimensions\n        self.bit_width = bit_width\n        # Assigned through the validating property below, so the guard","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/RyanCodrai/turbovec/blob/ccab9f325e6ce2a270a87daf01ae4e443bcf2d49/turbovec-python/python/turbovec/agno.py#L172-L208","documentation":"TurboQuantVectorDb supports quantization bit widths of 2, 3, or 4 bits per component. Any other bit_width value raises a ValueError because the underlying kernel only implements these quantization levels.","triggerScenarios":"Constructing TurboQuantVectorDb with bit_width outside {2,3,4}, e.g. bit_width=1, bit_width=8, or bit_width=None.","commonSituations":"Passing a bit width from another quantization library's vocabulary (e.g. 8-bit int8); computing bit_width from user config without validation; misreading docs that mention other widths for other libraries.","solutions":["Set bit_width to 2, 3, or 4 (4 gives highest fidelity, 2 the highest compression).","Validate/clamp any config-derived bit width to the supported set before construction.","If 8-bit or higher precision is needed, use a different vector DB backend without quantization."],"exampleFix":"// before\nTurboQuantVectorDb(embedder=e, bit_width=8)\n// after\nTurboQuantVectorDb(embedder=e, bit_width=4)","handlingStrategy":"validation","validationCode":"if bit_width not in (2, 3, 4):\n    bit_width = 4  # highest-fidelity supported default","typeGuard":null,"tryCatchPattern":"try:\n    db = TurboQuantVectorDb(embedder=e, bit_width=bw)\nexcept ValueError:\n    db = TurboQuantVectorDb(embedder=e, bit_width=4)","preventionTips":["Restrict bit_width config values to {2,3,4} at config-load time.","Clamp user-supplied bit widths to the nearest supported value.","Document that 8-bit/other widths are not supported by this backend."],"tags":["quantization","configuration","validation"],"backgroundTag":"value-out-of-range","analyzedSha":"ccab9f325e6ce2a270a87daf01ae4e443bcf2d49","analyzedAt":"2026-09-06T08:39:18.516Z","contentChangedAt":"2026-09-06T08:39:18.516Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}