cocoindex-io/cocoindex · error · ValueError

Invalid vector definition: {vector_def}

Error message

Invalid vector definition: {vector_def}

What it means

Raised by `_resolve_vector_def` when a QdrantVectorDef references a vector schema name that cannot be resolved: the resource schema's default vector schema is absent and no multi-vector schema exists under the given name. The definition is therefore invalid and the collection cannot be created.

Source

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

    Dense and sparse vectors share one namespace in Qdrant (the server
    rejects duplicate names across the two kinds), so a single dict holds
    both; the tagged union discriminates them.
    """

    vectors: dict[str, _ResolvedQdrantVectorDef | _ResolvedQdrantSparseVectorDef]


async def _resolve_vector_def(vector_def: QdrantVectorDef) -> _ResolvedQdrantVectorDef:
    resolved_schema: res_schema.VectorSchema | res_schema.MultiVectorSchema
    vs = await res_schema.get_vector_schema(vector_def.schema)
    if vs is not None:
        resolved_schema = vs
    else:
        mvs = await res_schema.get_multi_vector_schema(vector_def.schema)
        if mvs is not None:
            resolved_schema = mvs
        else:
            raise ValueError(f"Invalid vector definition: {vector_def}")
    return _ResolvedQdrantVectorDef(
        schema=resolved_schema,
        distance=vector_def.distance,
        multivector_comparator=vector_def.multivector_comparator,
    )


def _resolve_sparse_vector_def(
    sparse_vector_def: QdrantSparseVectorDef,
) -> _ResolvedQdrantSparseVectorDef:
    return _ResolvedQdrantSparseVectorDef(modifier=sparse_vector_def.modifier)


@dataclass(slots=True)
class CollectionSchema:
    """Schema definition for a Qdrant collection.

    Defines the vector fields for the collection. Each vector field is specified by name

View on GitHub (pinned to e84aa99b32)

Solutions

1. Declare/register the vector schema under the exact name referenced by QdrantVectorDef(schema=...).
2. Fix the schema name typo to match the registered vector schema.
3. If a default (unnamed) vector was intended, construct QdrantVectorDef without a schema name and ensure a default vector schema exists.
4. Verify resolution order: get_vector_schema for default, get_multi_vector_schema for named/multi vectors.

Example fix

// before
QdrantVectorDef(schema="embdeding", distance=Cosine)  # undeclared name
// after
QdrantVectorDef(schema="embedding", distance=Cosine)  # matches declared schema

# before create:
# declared = set(res_schema vector schema names)
# if vector_def.schema not in declared: raise ValueError(vector_def.schema)

def schema_is_declared(res_schema, name: str | None) -> bool:
    if name is None:
        return res_schema.get_vector_schema() is not None
    return res_schema.get_multi_vector_schema(name) is not None

try:
    collection = await QdrantCollection.create(..., vectors=vector_def)
except ValueError as e:
    if "Invalid vector definition" in str(e):
        logger.error("Vector schema %r not declared", vector_def.schema)
    else:
        raise

When it happens

Trigger: Creating a Qdrant collection with `QdrantVectorDef(schema='some_name', ...)` where `get_vector_schema` returns None and `get_multi_vector_schema('some_name')` also returns None — i.e. the named vector schema was never declared.

Common situations: Typo in the schema name; declaring vectors before registering their vector schema in the resource schema; renaming a vector schema and missing one call site.

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

• Invalid vector definition: {vectors}
• Settings.db_path must be provided
• Environment settings must provide Settings.db_path (or set C
• {env_name} is not set
• failed to parse environment variable {env_name}: {value}

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