{"record":{"id":"497d75201940f538","repo":"dotnet/efcore","slug":"the-vectordistance-function-can-only-be-used-wit","errorCode":null,"errorMessage":"The 'VectorDistance' function can only be used with a property mapped as a vector. Use 'IsVectorProperty()' in 'OnModelCreating' to configure the property as a vector.","messagePattern":"The 'VectorDistance' function can only be used with a property mapped as a vector\\. Use 'IsVectorProperty\\(\\)' in 'OnModelCreating' to configure the property as a vector\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/EFCore.Cosmos/Query/Internal/Translators/CosmosVectorSearchTranslator.cs","lineNumber":59,"sourceCode":"        }\n\n        if (useBruteForceExpression is not SqlConstantExpression { Value: var useBruteForceValue })\n        {\n            throw new InvalidOperationException(\n                CoreStrings.ArgumentNotConstant(\"useBruteForce\", nameof(CosmosDbFunctionsExtensions.VectorDistance)));\n        }\n\n        if (optionsExpression is not SqlConstantExpression { Value: var optionsValue })\n        {\n            throw new InvalidOperationException(\n                CoreStrings.ArgumentNotConstant(\"options\", nameof(CosmosDbFunctionsExtensions.VectorDistance)));\n        }\n\n        var options = (VectorDistanceOptions?)optionsValue;\n\n        var vectorMapping = vector1.TypeMapping as CosmosVectorTypeMapping\n            ?? vector2.TypeMapping as CosmosVectorTypeMapping\n            ?? throw new InvalidOperationException(CosmosStrings.VectorSearchRequiresVector);\n\n        var vectorType = vectorMapping.VectorType;\n\n        List<Expression> newArguments =\n        [\n            sqlExpressionFactory.ApplyTypeMapping(vector1, vectorMapping), sqlExpressionFactory.ApplyTypeMapping(vector2, vectorMapping)\n        ];\n\n        if (useBruteForceValue is not null)\n        {\n            newArguments.Add(useBruteForceExpression);\n        }\n\n        if (options is not null)\n        {\n            // If the options are provided but not useBruteForce, we need to explicitly specify the default for the\n            // latter (false)\n            if (useBruteForceValue is null)","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/dotnet/efcore/blob/3a2006ef569de08368d59db5e1468aa8f407e4f8/src/EFCore.Cosmos/Query/Internal/Translators/CosmosVectorSearchTranslator.cs#L41-L77","documentation":"CosmosVectorSearchTranslator throws VectorSearchRequiresVector when neither operand of EF.Functions.VectorDistance has a CosmosVectorTypeMapping. At least one operand must be a property configured as a vector so the provider can determine the element type, dimensions, and SQL shape. Without a vector mapping the call cannot be translated.","triggerScenarios":"Calling EF.Functions.VectorDistance(a, b) where neither a nor b is a vector-typed property, e.g. passing two raw array parameters.","commonSituations":"Forgetting to call IsVectorProperty(dimension) in OnModelCreating for the property used in VectorDistance; passing two client-side arrays.","solutions":["Configure the vector property: modelBuilder.Entity<T>().Property(x => x.Embedding).IsVectorProperty(dimensions);","Ensure at least one operand of VectorDistance is the configured vector property (not a raw parameter on both sides).","Verify the property's column type is a vector type (e.g. Vector<float>) and the type mapping resolves to CosmosVectorTypeMapping."],"exampleFix":"// before\nmodelBuilder.Entity<Item>().Property(x => x.Embedding);\n\n// after\nmodelBuilder.Entity<Item>().Property(x => x.Embedding).IsVectorProperty(1536);","handlingStrategy":"validation","validationCode":"// At model build, assert the property used in VectorDistance is configured as a vector.\nvar prop = entityType.FindProperty(nameof(Item.Embedding));\nif (prop?.GetVectorTypeMapping() is null)\n    throw new InvalidOperationException($\"{entityType.DisplayName()}.{nameof(Item.Embedding)} must be configured with IsVectorProperty.\");","typeGuard":"static bool IsVectorProperty(IProperty p) => p.GetTypeMapping() is CosmosVectorTypeMapping;","tryCatchPattern":null,"preventionTips":["Configure vector properties with IsVectorProperty(dimensions) in OnModelCreating.","Always pass the configured vector property as one operand of VectorDistance.","Add a model-build validator that asserts vector-search properties have CosmosVectorTypeMapping."],"tags":["cosmos","vector-search","model","type-mapping"],"backgroundTag":null,"analyzedSha":"3a2006ef569de08368d59db5e1468aa8f407e4f8","analyzedAt":"2026-08-11T23:42:04.146Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}