On this page
vector dimension mismatch#
ERROR: invalid argument for function l2_distance: vector dimension mismatchThe query vector and the column disagree. Check the declared dimension:
-- The column was declared with 3 dimensions; this query passes 2:
SELECT [1.0, 0.0] <-> [1.0, 0.0, 0.0];Fix: pad/truncate the query vector to the column's dimension, or recreate the table with the model's true dimension. Dimension errors also appear at INSERT when a literal has the wrong element count.
invalid input syntax for type vector#
Covers non-numeric elements in dense literals ([1.0, 'x']), NaN/Infinity, out-of-range integers for quantized columns, and dense-bracket literals into BINARY columns (vector kind mismatch: value is Dense, column is Binary — use the '0101…' string form instead).
CREATE VECTOR index inside explicit transactions is not yet supported#
BEGIN;
CREATE INDEX docs_emb_hnsw ON docs USING hnsw (embedding); -- refused
COMMIT;Fix: run CREATE INDEX in autocommit (a plain statement from psql or a driver without an open transaction). Note many drivers wrap statements in transactions implicitly — with psycopg, either use autocommit mode or execute the DDL outside the transaction block. Extended-protocol clients hitting CREATE/DROP DATABASE inside a transaction see the analogous cannot be executed inside a transaction block error.
Empty or missing results#
NULLembeddings never match: addWHERE embedding IS NOT NULLto confirm whether nulls are the cause.- A
LIMITwithoutORDER BY distancereturns arbitrary rows — check the query shape. - Filtering to a category with no rows returns no rows regardless of vector similarity — check the filter alone first (
SELECT count(*) ... WHERE <filter>).
Slow queries#
EXPLAINthe query: exact scan or index path? Small tables deliberately scan — that is not a bug.- Check
SHOW vector.ann_enabled;—offforces exact scans. - Check row count against
vector.auto_ann_min_rows(default 4096): below it, exact is expected. - Filtered queries always run exact in
v0.1.0— narrow the filter or partition the data. - Never benchmark on a debug build; use the release binary.
function "inner_product" is not supported#
There is no inner_product function. Use dot_product(a, b) for the plain dot product, neg_inner_product(a, b) for the negated form, or the <#> operator. See Distance operators.
Still stuck?#
- Similarity search for query shape reference.
- Limitations to check whether the path is experimental.
- Troubleshooting for server-level diagnostics.