cocoindex-io/cocoindex · critical · RuntimeError

zvec operation failed: code={status.code()} message={status.

Error message

zvec operation failed: code={status.code()} message={status.message()}

What it means

_check_status inspects the Status object(s) returned by zvec operations and raises RuntimeError if any status is not OK. This surfaces a failed write/upsert/delete inside the zvec engine with its native code and message.

Source

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

class _DocValue(NamedTuple):
    doc_id: str
    vectors: dict[str, Any]
    fields: dict[str, Any]


class _DocAction(NamedTuple):
    doc_id: _DocId
    value: _DocValue | None  # None means delete


def _check_status(result: Any) -> None:
    """Raise if any zvec Status in the result is not OK."""
    statuses = result if isinstance(result, list) else [result]
    for status in statuses:
        if not status.ok():
            raise RuntimeError(
                f"zvec operation failed: code={status.code()} "
                f"message={status.message()}"
            )


def _build_doc(value: _DocValue) -> Any:
    vectors = {k: v for k, v in value.vectors.items() if v is not None}
    fields = {k: v for k, v in value.fields.items() if v is not None}
    return _zvec.Doc(
        id=value.doc_id,
        vectors=vectors or None,
        fields=fields or None,
    )


class _DocHandler(coco.TargetHandler[_DocValue, bytes]):
    """Handler for document-level target states within a collection."""

View on GitHub (pinned to e84aa99b32)

Solutions

1. Read the embedded zvec code/message to identify the engine-level failure.
2. Check free disk space and filesystem health on the collection's storage path.
3. Retry the update; if the collection is corrupted, rebuild it (drop and re-declare the target state).

try:
    await app.update()
except RuntimeError as e:
    if str(e).startswith("zvec operation failed"):
        code, msg = e.args[0].split("message=")
        logging.critical("zvec write failed: %s", msg)
        # inspect disk space / collection health, then retry or rebuild

When it happens

Trigger: Calling _apply_actions (syncing declared rows to the zvec collection) when the underlying zvec write returns a non-OK Status, e.g. corrupted segment, disk full, or an engine-level write error.

Common situations: Disk exhaustion or I/O errors on the local vector store path; corrupted collection files; resource limits inside the zvec engine during bulk upserts.

Related errors

• Primary key column {primary_key!r} must be a scalar field, g
• zvec collections require exactly one primary key column (map
• Unsupported metric type: {metric!r}
• Unsupported quantize type: {quantize!r}
• Primary key {schema.primary_key!r} value cannot be None.

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