RyanCodrai/turbovec · error · ValueError

Embedder.dimensions must be set.

Error message

Embedder.dimensions must be set.

What it means

After checking the embedder exists, TurboQuantVectorDb reads embedder.dimensions to allocate the index. If dimensions is None (the embedder has not resolved its output dimension), a ValueError is raised because the index size cannot be determined.

Source

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

        :param reranker: Optional Agno reranker applied to the result set
            after vector retrieval.
        :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

View on GitHub (pinned to ccab9f325e)

Solutions

1. Set dimensions explicitly on the embedder, e.g. OpenAIEmbedder(dimensions=1536).
2. Use a different embedder class whose dimensions are known without an API call.
3. Verify model/params: some embedders expose dimensions only after configuring a specific model.

Example fix

// before
embedder = OpenAIEmbedder(model="text-embedding-3-large")
// after
embedder = OpenAIEmbedder(model="text-embedding-3-large", dimensions=3072)

if embedder.dimensions is None:
    embedder.dimensions = KNOWN_DIMENSIONS[embedder.model]

def dimensions_known(embedder: Embedder) -> bool:
    return isinstance(getattr(embedder, "dimensions", None), int) and embedder.dimensions > 0

try:
    db = TurboQuantVectorDb(embedder=embedder)
except ValueError as e:
    if "dimensions" in str(e):
        embedder.dimensions = 1536  # or per-model lookup
        db = TurboQuantVectorDb(embedder=embedder)

When it happens

Trigger: Passing an embedder whose dimensions attribute is None — typically an embedder constructed without an explicit dimensions/model config that resolves dimensions lazily, used before any embedding has been performed.

Common situations: Custom or lightweight embedder subclasses that never set dimensions; embedders that infer dimensions on first embed call; copying embedder config from another vector DB that does not need dimensions upfront.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• {param} must be one of {list(_VALID_MODES)}, got {value!r}
• bit_width must be 2, 3, or 4, got {bit_width}
• TurboQuantVectorDb only supports search_type=SearchType.vect
• TurboQuantVectorDb supports distance=Distance.cosine or dist

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