RyanCodrai/turbovec · error · ValueError

bit_width must be 2, 3, or 4, got {bit_width}

Error message

bit_width must be 2, 3, or 4, got {bit_width}

What it means

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.

Source

Thrown at turbovec-python/python/turbovec/agno.py:190

        :param path: Optional directory for save/load persistence. When
            given to the constructor, :meth:`create` loads existing data
            from this path if present.
        """
        super().__init__(
            id=id,
            name=name,
            description=description,
            similarity_threshold=similarity_threshold,
        )
        if embedder is None:
            raise ValueError(
                "`embedder` is required; turbovec needs the embedder's "
                "`dimensions` to size the underlying index."
            )
        if embedder.dimensions is None:
            raise ValueError("Embedder.dimensions must be set.")
        if bit_width not in (2, 3, 4):
            raise ValueError(f"bit_width must be 2, 3, or 4, got {bit_width}")
        if search_type != SearchType.vector:
            raise ValueError(
                f"TurboQuantVectorDb only supports search_type=SearchType.vector; "
                f"got {search_type}. Use LanceDb / Chroma / etc. for keyword "
                f"or hybrid search."
            )
        if distance not in (Distance.cosine, Distance.max_inner_product):
            raise ValueError(
                f"TurboQuantVectorDb supports distance=Distance.cosine or "
                f"distance=Distance.max_inner_product; got {distance}. "
                f"L2 distance is not supported by the underlying "
                f"inner-product kernel."
            )

        self.embedder: Embedder = embedder
        self.dimensions: int = embedder.dimensions
        self.bit_width = bit_width
        # Assigned through the validating property below, so the guard

View on GitHub (pinned to ccab9f325e)

Solutions

1. Set bit_width to 2, 3, or 4 (4 gives highest fidelity, 2 the highest compression).
2. Validate/clamp any config-derived bit width to the supported set before construction.
3. If 8-bit or higher precision is needed, use a different vector DB backend without quantization.

Example fix

// before
TurboQuantVectorDb(embedder=e, bit_width=8)
// after
TurboQuantVectorDb(embedder=e, bit_width=4)

if bit_width not in (2, 3, 4):
    bit_width = 4  # highest-fidelity supported default

try:
    db = TurboQuantVectorDb(embedder=e, bit_width=bw)
except ValueError:
    db = TurboQuantVectorDb(embedder=e, bit_width=4)

When it happens

Trigger: Constructing TurboQuantVectorDb with bit_width outside {2,3,4}, e.g. bit_width=1, bit_width=8, or bit_width=None.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• {param} must be one of {list(_VALID_MODES)}, got {value!r}
• duplicate id in batch: {k!r}
• {prefix} {version}; this turbovec accepts versions {list(com
• persisted store is corrupt: {len(extraneous)} {what} id(s) p
• `embedder` is required; turbovec needs the embedder's `dimen

AI-assisted analysis of RyanCodrai/turbovec@ccab9f325e (2026-09-06). Data as JSON: /api/errors/fb56fdf2025174a7. Report an issue: GitHub.