{"record":{"id":"24bb042c0482d8b7","repo":"cocoindex-io/cocoindex","slug":"invalid-pgvector-dimension-vector-schema-size","errorCode":null,"errorMessage":"Invalid pgvector dimension: {vector_schema.size}","messagePattern":"Invalid pgvector dimension: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/postgres/_target.py","lineNumber":289,"sourceCode":"    type_info = analyze_type_info(python_type)\n\n    # Check for PgType annotation override\n    for annotation in type_info.annotations:\n        if isinstance(annotation, PgType):\n            return _TypeMapping(annotation.pg_type, annotation.encoder)\n\n    base_type = type_info.base_type\n\n    # Check direct leaf type mappings\n    if base_type in _LEAF_TYPE_MAPPINGS:\n        return _LEAF_TYPE_MAPPINGS[base_type]\n\n    # NumPy ndarray: map to pgvector type bases; dimension is handled at the schema layer.\n    if base_type is np.ndarray:\n        if vector_schema is None:\n            raise ValueError(\"VectorSpecProvider is required for NumPy ndarray type.\")\n        if vector_schema.size <= 0:\n            raise ValueError(f\"Invalid pgvector dimension: {vector_schema.size}\")\n\n        # Default to `vector` (float32/float64/int64/etc.). Use `halfvec` for float16.\n        base = \"halfvec\" if vector_schema.dtype in (np.half, np.float16) else \"vector\"\n        return _TypeMapping(\n            pg_type=f\"{base}({vector_schema.size})\", encoder=_vector_encoder\n        )\n\n    elif vector_schema is not None:\n        raise ValueError(\n            f\"VectorSpecProvider is only supported for NumPy ndarray type. Got type: {python_type}\"\n        )\n\n    # Complex types that need JSON encoding\n    if isinstance(\n        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)\n    ):\n        return _JSONB_MAPPING\n","sourceCodeStart":271,"sourceCodeEnd":307,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/postgres/_target.py#L271-L307","documentation":"Validation in the PostgreSQL target's type mapping. An np.ndarray column maps to pgvector, whose dimension must be known and positive; it is taken from the VectorSchema provided via an Annotated NDArray or column_overrides. This ValueError fires when the declared vector size is invalid (zero/negative/missing), since no well-typed vector column can be created. Declare the field with a VectorSchema carrying a positive dimension.","triggerScenarios":"Supplying a VectorSchemaProvider whose size is 0 or negative, e.g. VectorSchemaProvider(size=0) or a provider computing size from an empty/uninitialized array.","commonSituations":"Computing dimension from an embedding model output before it has run, copy-paste of a placeholder size, or dynamic sizing that evaluates to 0.","solutions":["Set the provider size to the actual embedding dimension (e.g. 384, 768, 1536).","If size is computed dynamically, assert it is > 0 before constructing the target.","Check the provider implementation for an off-by-default/uninitialized size value."],"exampleFix":"// before\noverrides = {\"embedding\": VectorSchemaProvider(size=0)}\n// after\noverrides = {\"embedding\": VectorSchemaProvider(size=768)}","handlingStrategy":"validation","validationCode":"dim = get_vector_size()\nassert isinstance(dim, int) and dim > 0, f\"pgvector dim must be positive, got {dim}\"","typeGuard":"def valid_vector_dim(provider) -> bool:\n    size = provider.size\n    return isinstance(size, int) and size > 0","tryCatchPattern":"try:\n    target = await PgTableTarget.from_class(Row, primary_key=[\"id\"], column_overrides=ov)\nexcept ValueError as e:\n    if \"Invalid pgvector dimension\" in str(e):\n        ov[\"embedding\"] = VectorSchemaProvider(size=EMBEDDING_DIM)","preventionTips":["Never hardcode 0/-1 placeholders; use the model's real dimension.","Assert dim > 0 wherever the size is computed dynamically.","Keep dimension constants in one place shared by model and schema."],"tags":["python","pgvector","configuration","validation"],"backgroundTag":"value-out-of-range","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}