RyanCodrai/turbovec · error · ValueError

{param} must be one of {list(_VALID_MODES)}, got {value!r}

Error message

{param} must be one of {list(_VALID_MODES)}, got {value!r}

What it means

validate_similarity checks that a similarity mode string is one of the supported values in _VALID_MODES before it is used to configure a similarity search. If the value is unknown, a ValueError names the parameter and lists the valid options. This fail-fast validation prevents an invalid mode from silently degrading search results.

Source

Thrown at turbovec-python/python/turbovec/_similarity.py:36

reference stores (LangChain's ``InMemoryVectorStore`` maps the resulting
NaN cosine to 0.0; Haystack's ``InMemoryDocumentStore`` substitutes a
norm of 1, which leaves the zero dot product intact).
"""

from __future__ import annotations

import numpy as np

COSINE = "cosine"
DOT_PRODUCT = "dot_product"
_VALID_MODES = (COSINE, DOT_PRODUCT)


def validate_similarity(value: str, *, param: str = "similarity") -> str:
    """Return ``value`` if it names a supported similarity mode, else
    raise a ``ValueError`` naming the parameter and the valid options."""
    if value not in _VALID_MODES:
        raise ValueError(
            f"{param} must be one of {list(_VALID_MODES)}, got {value!r}"
        )
    return value


def l2_normalize_rows(vectors: np.ndarray) -> np.ndarray:
    """Return a float32 copy of the 2D batch ``vectors`` with every row
    L2-normalized. Rows with zero norm are kept as-is (see module
    docstring). Pure computation — safe to run outside store locks."""
    norms = np.linalg.norm(vectors, axis=1, keepdims=True)
    # Substitute 1.0 for zero norms so zero rows pass through unchanged
    # instead of dividing by zero.
    out = vectors / np.where(norms == 0.0, 1.0, norms)
    return np.ascontiguousarray(out, dtype=np.float32)


__all__ = [
    "COSINE",

View on GitHub (pinned to ccab9f325e)

Solutions

1. Use one of the modes listed in the error message (from _VALID_MODES) exactly as spelled.
2. Check the current library docs/source for the valid mode names — they may have changed between versions.
3. If the value comes from config/user input, validate it against the supported list before constructing the object.

Example fix

// before
index = TurboIndex(similarity="cosine_sim")
// after
index = TurboIndex(similarity="cosine")  # must be in _VALID_MODES

from turbovec._similarity import validate_similarity, _VALID_MODES
mode = validate_similarity(cfg.get("similarity", "cosine"))

try:
    mode = validate_similarity(user_value)
except ValueError as e:
    print(e)  # message lists all valid modes
    mode = "cosine"

When it happens

Trigger: Passing an unsupported string for the similarity parameter to validate_similarity (typically via __init__ of a similarity/index object), e.g. similarity='euclidian' (typo) or 'cosine_similarity' instead of a valid mode name.

Common situations: Typos in mode names, copying config from another vector library with different mode vocabulary, building the mode string from user input or environment variables without whitelist validation, or a renamed mode after a library upgrade.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• bit_width must be 2, 3, or 4, got {bit_width}
• 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/5bcfab29c82472fc. Report an issue: GitHub.