lancedb/lancedb · error · ValueError

Invalid output_dimension

Error message

Invalid output_dimension {self.output_dimension} for {self.name}. Valid options: {self._VALID_DIMENSIONS}

What it means

VoyageAI flexible-dimension models (e.g. voyage-3 family) accept a configurable output_dimension, but only within a fixed set of valid values. When ndims() is called and the configured output_dimension is not in _VALID_DIMENSIONS, this ValueError is raised. It catches configuration mistakes early rather than failing at query time with dimension mismatches.

Solutions

Set output_dimension to one of the values listed in the error message's _VALID_DIMENSIONS for that model.
Omit output_dimension entirely to use the model default (1024).
Check the VoyageAI documentation for the exact valid dimensions of your specific model name.

Example fix

// before
func = get_registry().get("voyageai").create(name="voyage-3-large", output_dimension=500)
// after
func = get_registry().get("voyageai").create(name="voyage-3-large", output_dimension=1024)

Defensive patterns

Strategy: validation

Validate before calling

VALID = {256, 512, 1024, 2048}  # check _VALID_DIMENSIONS for your model
if output_dimension is not None and output_dimension not in VALID:
    raise ValueError(f"output_dimension must be one of {sorted(VALID)}")

Type guard

def has_valid_output_dimension(func) -> bool:
    od = getattr(func, "output_dimension", None)
    return od is None or od in func._VALID_DIMENSIONS

Try / catch

try:
    table = db.create_table("t", mode="overwrite", embedding_dimensions=func.ndims())
except ValueError as e:
    if "Invalid output_dimension" in str(e):
        func.output_dimension = None  # fall back to model default
        table = db.create_table("t", mode="overwrite", embedding_dimensions=func.ndims())
    else:
        raise

Prevention

Only set output_dimension from the model's documented valid list, never arbitrary values.
Check VoyageAI model docs for the exact dimension options of your chosen model.
Omit output_dimension unless you specifically need a reduced vector size.

When it happens

Trigger: Creating a VoyageAIEmbeddingFunction with a flexible-dim model name and an output_dimension outside the valid set (e.g. 500 or 999 for a model supporting 256/512/1024/2048), then creating a table or querying, which triggers ndims().

Common situations: Typo or guess at valid dimensions; copying an output_dimension valid for one flexible model to another that supports a different set; hardcoding a dimension from old model documentation.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of lancedb/lancedb@c7b051aff7 (2026-09-08). Data as JSON: /api/errors/7797e4e3a1e53cd8. Report an issue: GitHub.

Appendix: source

Thrown at python/python/lancedb/embeddings/voyageai.py:252

        "voyage-code-2",
    ]
    multimodal_embedding_models: list = ["voyage-multimodal-3", "voyage-multimodal-3.5"]
    contextual_embedding_models: list = ["voyage-context-3"]

    def _is_multimodal_model(self, model_name: str):
        return (
            model_name in self.multimodal_embedding_models or "multimodal" in model_name
        )

    def _is_contextual_model(self, model_name: str):
        return model_name in self.contextual_embedding_models or "context" in model_name

    def ndims(self):
        # Handle flexible dimension models
        if self.name in self._FLEXIBLE_DIM_MODELS:
            if self.output_dimension is not None:
                if self.output_dimension not in self._VALID_DIMENSIONS:
                    raise ValueError(
                        f"Invalid output_dimension {self.output_dimension} "
                        f"for {self.name}. Valid options: {self._VALID_DIMENSIONS}"
                    )
                return self.output_dimension
            return 1024  # default dimension

        if self.name == "voyage-3-lite":
            return 512
        elif self.name == "voyage-code-2":
            return 1536
        elif self.name in [
            "voyage-4",
            "voyage-4-lite",
            "voyage-4-large",
            "voyage-context-3",
            "voyage-3.5",
            "voyage-3.5-lite",
            "voyage-3",

View on GitHub (pinned to c7b051aff7)