{"record":{"id":"5d21a90b51871144","repo":"weaviate/weaviate","slug":"normalized-distance-w","errorCode":null,"errorMessage":"normalized distance: %w","messagePattern":"normalized distance: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"usecases/vectorizer/distance.go","lineNumber":24,"sourceCode":"//\n//  Copyright © 2016 - 2026 Weaviate B.V. All rights reserved.\n//\n//  CONTACT: hello@weaviate.io\n//\n\npackage vectorizer\n\nimport (\n\t\"fmt\"\n\t\"math\"\n)\n\n// NormalizedDistance between two arbitrary vectors, errors if dimensions don't\n// match, will return results between 0 (no distance) and 1 (maximum distance)\nfunc NormalizedDistance(a, b []float32) (float32, error) {\n\tsim, err := cosineSim(a, b)\n\tif err != nil {\n\t\treturn 1, fmt.Errorf(\"normalized distance: %w\", err)\n\t}\n\n\treturn (1 - sim) / 2, nil\n}\n\nfunc cosineSim(a, b []float32) (float32, error) {\n\tif len(a) != len(b) {\n\t\treturn 0, fmt.Errorf(\"vectors have different dimensions\")\n\t}\n\n\tvar (\n\t\tsumProduct float64\n\t\tsumASquare float64\n\t\tsumBSquare float64\n\t)\n\n\tfor i := range a {\n\t\tsumProduct += float64(a[i] * b[i])","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/usecases/vectorizer/distance.go#L6-L42","documentation":"NormalizedDistance computes (1 - cosine)/2 between two vectors and wraps any error from cosineSim with this prefix. The only source is dimension mismatch, so this error indicates the compared vectors were produced with different dimensionality.","triggerScenarios":"Calling vectorizer.NormalizedDistance(a, b) where len(a) != len(b) — e.g. mixing vectors from different vectorizers, different target vectors, or before/after a vectorizer model change.","commonSituations":"Schema migration changing vectorizer/model (dimension change) while old vectors remain; comparing cross-target-vector embeddings in multi-vector setups; hand-built vectors with wrong length.","solutions":["Ensure both vectors come from the same model/dimension before comparing.","Re-vectorize the collection after any vectorizer/model change.","Validate vector lengths at call sites before computing distances.","Add a pre-call length equality guard in calling code."],"exampleFix":"// before\nsim, _ := vectorizer.NormalizedDistance(a, b)\n// after\nif len(a) != len(b) { return fmt.Errorf(\"dim mismatch: %d vs %d\", len(a), len(b)) }\nsim, err := vectorizer.NormalizedDistance(a, b)","handlingStrategy":"validation","validationCode":"func canCompare(a, b []float32) bool { return len(a) == len(b) && len(a) > 0 }","typeGuard":"func sameDims(a, b []float32) bool { return len(a) == len(b) }","tryCatchPattern":"sim, err := vectorizer.NormalizedDistance(a, b)\nif err != nil {\n  var dimErr bool = strings.Contains(err.Error(), \"different dimensions\")\n  if dimErr { return revectorizeAndRetry() }\n  return err\n}","preventionTips":["Pin one vectorizer/model per collection and record its dimension.","Re-vectorize the whole collection after model changes.","Validate vector length at ingestion time.","Use named/target vectors consistently in queries."],"tags":["vectorizer","math","dimension-mismatch"],"backgroundTag":"vector-dimension-mismatch","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}