cocoindex-io/cocoindex · error · ValueError

Unsupported metric type: {metric!r}

Error message

Unsupported metric type: {metric!r}

What it means

Enum-style mapper guard in _metric_type, called while building the zvec collection schema. Only 'cosine', 'ip', and 'l2' (case-insensitive) map to zvec MetricType values; any other string would otherwise be passed through to zvec and fail deep inside the engine with an opaque error. This ValueError fires when a metric config value is misspelled or unsupported. Use one of cosine, ip, or l2.

Source

Thrown at python/cocoindex/connectors/zvec/_target.py:522

            )

        record_info = RecordType(record_type)
        columns: dict[str, _Column] = {}
        for fld in record_info.fields:
            override = column_overrides.get(fld.name) if column_overrides else None
            columns[fld.name] = await _resolve_column(fld.name, fld.type_hint, override)
        return cls(columns, primary_key[0], row_type=record_type)


def _metric_type(metric: str) -> Any:
    key = metric.lower()
    if key == "cosine":
        return _zvec.MetricType.COSINE
    if key == "ip":
        return _zvec.MetricType.IP
    if key == "l2":
        return _zvec.MetricType.L2
    raise ValueError(f"Unsupported metric type: {metric!r}")


def _quantize_type(quantize: str) -> Any | None:
    key = quantize.lower()
    if key == "none":
        return None
    if key == "fp16":
        return _zvec.QuantizeType.FP16
    if key == "int8":
        return _zvec.QuantizeType.INT8
    if key == "int4":
        return _zvec.QuantizeType.INT4
    raise ValueError(f"Unsupported quantize type: {quantize!r}")


def _build_zvec_schema(collection_name: str, schema: CollectionSchema[Any]) -> Any:
    fields: list[Any] = []
    vectors: list[Any] = []

View on GitHub (pinned to e84aa99b32)

Solutions

1. Change the metric to one of: 'cosine', 'ip', 'l2'.
2. Use 'l2' for euclidean distance, 'ip' for dot/inner product.
3. Validate metric strings against the allowed set before declaring the collection.

Example fix

// before
Column(kind="dense", dim=768, metric="euclidean")
// after
Column(kind="dense", dim=768, metric="l2")

ALLOWED = {"cosine", "ip", "l2"}
assert metric.lower() in ALLOWED, f"metric must be one of {ALLOWED}"

try:
    target = collection_target(...)
except ValueError as e:
    if "metric" in str(e): ...

When it happens

Trigger: Declaring a zvec collection with a vector column whose metric is set to an unsupported name, e.g. 'euclidean', 'hamming', 'dot', or 'COSINE' with different casing than the accepted keys.

Common situations: Copying metric names from other vector DBs (pgvector/Qdrant/FAISS use different spellings like 'euclidean' or 'dot'); typo in config.

Related errors

• Unsupported quantize type: {quantize!r}
• Unsupported LanceDB vector index type: {spec.index_type!r}.
• Unsupported pgvector metric '{metric}' for PostgreSQL type '
• Primary key column {primary_key!r} must be a scalar field, g
• zvec collections require exactly one primary key column (map

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