{"record":{"id":"f6f96de4a2d3fc03","repo":"cocoindex-io/cocoindex","slug":"invalid-vector-dimension-vector-schema-size-f6f96d","errorCode":null,"errorMessage":"Invalid vector dimension: {vector_schema.size}","messagePattern":"Invalid vector dimension: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/surrealdb/_target.py","lineNumber":286,"sourceCode":"    type_info = analyze_type_info(python_type)\n\n    # Check for SurrealType annotation override\n    for annotation in type_info.annotations:\n        if isinstance(annotation, SurrealType):\n            return _TypeMapping(annotation.surreal_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 array<float, N>\n    if base_type is np.ndarray:\n        if vector_schema is None:\n            raise ValueError(\"VectorSchemaProvider is required for NumPy ndarray type.\")\n        if vector_schema.size <= 0:\n            raise ValueError(f\"Invalid vector dimension: {vector_schema.size}\")\n\n        return _TypeMapping(\n            surreal_type=f\"array<float, {vector_schema.size}>\",\n            encoder=_ndarray_encoder,\n        )\n\n    elif vector_schema is not None:\n        raise ValueError(\n            f\"VectorSchemaProvider is only supported for NumPy ndarray type. \"\n            f\"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 _OBJECT_MAPPING\n","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/surrealdb/_target.py#L268-L304","documentation":"A VectorSchemaProvider attached to an np.ndarray field reports a non-positive vector size. SurrealDB's array<float, N> requires N to be a positive dimension, so CocoIndex rejects the mapping when size <= 0.","triggerScenarios":"Passing VectorSchemaProvider with size=0 or a negative size (e.g. an uninitialized/0-length dimension variable, or reading the size from an empty array's shape) while declaring a SurrealDB vector column.","commonSituations":"Computing the dimension from an empty sample array; a config default of 0 that was never set; typo like size=-1 as a placeholder.","solutions":["Set VectorSchemaProvider(size=N) to the actual embedding dimension (e.g. 384, 768).","Derive N from the embedding model's output dimension constant instead of runtime sample data.","Add a startup assertion that the configured size matches model output."],"exampleFix":"// before\nVectorSchemaProvider(size=0)\n// after\nVectorSchemaProvider(size=768)","handlingStrategy":"validation","validationCode":"if vector_schema.size <= 0:\n    raise ValueError(f\"vector size must be positive, got {vector_schema.size}\")","typeGuard":"def has_valid_vector_dimension(vs) -> bool:\n    return vs is not None and vs.size > 0","tryCatchPattern":"try:\n    target = table_target(record_type, ...)\nexcept ValueError as e:\n    if \"Invalid vector dimension\" in str(e):\n        # set size to the embedding model's output dimension\n        ...","preventionTips":["Use the embedding model's documented output dimension as a constant, not derived runtime data.","Never default vector size to 0; require explicit configuration.","Assert dimension matches model output once at startup."],"tags":["surrealdb","vector","dimension","config"],"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-17T15:17:12.973Z"}