cocoindex-io/cocoindex · error · ValueError

Unsupported multivector comparator: {comparator}

Error message

Unsupported multivector comparator: {comparator}

What it means

For Qdrant multivectors, the connector accepts only the "max_sim" comparator (matched case-insensitively), mapping it to qdrant_models.MultiVectorComparator.MAX_SIM. Any other comparator string raises this ValueError when the vector params are built.

Source

Thrown at python/cocoindex/connectors/qdrant/_target.py:675

def _distance_from_spec(distance: str) -> qdrant_models.Distance:
    distance_key = distance.lower()
    if distance_key in ("cosine",):
        return qdrant_models.Distance.COSINE
    if distance_key in ("dot", "dotproduct"):
        return qdrant_models.Distance.DOT
    if distance_key in ("euclid", "euclidean", "l2"):
        return qdrant_models.Distance.EUCLID
    raise ValueError(f"Unsupported Qdrant distance metric: {distance}")


def _multivector_comparator(
    comparator: str,
) -> qdrant_models.MultiVectorComparator:
    """Convert multivector comparator string to Qdrant enum."""
    if comparator.lower() == "max_sim":
        return qdrant_models.MultiVectorComparator.MAX_SIM
    raise ValueError(f"Unsupported multivector comparator: {comparator}")


def _sparse_modifier_from_spec(
    modifier: Literal["idf"] | None,
) -> qdrant_models.Modifier | None:
    if modifier is None:
        return None
    if modifier == "idf":
        return qdrant_models.Modifier.IDF
    raise ValueError(f"Unsupported Qdrant sparse vector modifier: {modifier}")


def _vector_params_from_def(
    vector_def: _ResolvedQdrantVectorDef,
) -> qdrant_models.VectorParams:
    """Convert a resolved vector definition to Qdrant VectorParams."""
    resolved_schema = vector_def.schema
    multivector_config = None

View on GitHub (pinned to e84aa99b32)

Solutions

1. Set multivector_comparator to "max_sim" (case-insensitive: "MAX_SIM" also works).
2. If you don't need multivector behavior, omit multivector_comparator and use a plain VectorSchema.
3. Check for hyphen vs underscore: use "max_sim", not "max-sim".

Example fix

// before
QdrantVectorDef(schema=mv_schema, distance="cosine", multivector_comparator="max-sim")
// after
QdrantVectorDef(schema=mv_schema, distance="cosine", multivector_comparator="max_sim")

assert comparator.lower() == "max_sim", f"only 'max_sim' supported, got {comparator!r}"

isinstance(comparator, str) and comparator.lower() == "max_sim"

try:
    schema = await CollectionSchema.create(vectors=def_)
except ValueError as e:
    raise ConfigError(f"multivector comparator invalid: {e}") from None

When it happens

Trigger: Setting multivector_comparator on QdrantVectorDef to anything other than "max_sim" (e.g. "maxsim", "dot", "euclid") while using a multivector VectorSchema; triggered via _vector_params_from_def during collection creation.

Common situations: Guessing comparator names because Qdrant's API only has MAX_SIM; typos like "max-sim" (with hyphen) — note hyphen is NOT accepted, only "max_sim" case-insensitively; copying comparator values from other libraries.

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

• Unsupported Qdrant distance metric: {distance}
• Unsupported Qdrant sparse vector modifier: {modifier}
• Invalid metric name: {metric}
• qdrant-client is required to use the Qdrant connector. Pleas
• Invalid vector definition: {vector_def}

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/fdbe0f3327af93d7. Report an issue: GitHub.