ruvnet/ruflo · error

Vector dimension mismatch

Error message

Vector dimension mismatch: ${a.length} vs ${b.length}

What it means

Thrown by the cosineSimilarity helper in vector-db.ts when the two vectors it was asked to compare have different lengths. In practice this means a search/query vector whose length differs from the vectors stored in the VectorDB (constructed with a fixed dimensions argument). Because cosine similarity iterates a[i]*b[i] for the full length, mismatched vectors cannot be compared, so it fails fast.

Solutions

1. Embed queries with the same model (and thus the same dimension) used when inserting vectors
2. After changing embedding model/dimension, rebuild the vector store: clear() and re-insert re-embedded vectors
3. Validate query.length against the dimension passed to the VectorDB constructor before calling search

Example fix

// before
const db = new VectorDB(384);
// ...later, model changed to 768-dim:
db.search(embed768(query)); // throws 'Vector dimension mismatch: 768 vs 384'

// after
if (embed768(query).length !== 384) {
  throw new Error('embedding model drift — rebuild the store or migrate vectors');
}
db.search(Float32Array.from(embed384(query)));

const query = Float32Array.from(rawQuery);
if (query.length !== DB_DIMENSIONS) { // the number passed to new VectorDB(dimensions)
  throw new Error(`query is ${query.length}-dim but store is ${DB_DIMENSIONS}-dim; re-embed or rebuild store`);
}
db.search(query);

const isCompatibleVector = (v: Float32Array, dims: number): boolean => v instanceof Float32Array && v.length === dims;

try {
  db.search(query);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Vector dimension mismatch')) {
    // dimension drift: rebuild the store with re-embedded vectors, then retry once
  } else throw e;
}

When it happens

Trigger: Constructing VectorDB with dimensions=N and inserting vectors of length N, then calling search/similarity with a query vector of length M != N; or inserting vectors of inconsistent lengths in the first place so two stored vectors get compared.

Common situations: Switching embedding models after the DB was populated (old stored 384-dim vectors, new 768-dim queries), loading a persisted DB built under an old configuration, feeding raw token arrays instead of model embeddings.

Related errors

• Dimensions ( ) must be divisible by numSubvectors ( )
• each record requires a non-empty numeric vector
• embedBatch() expects an array of strings
• embedding failed
• Embedding must be Float32Array of length

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/9d2b4ce5439ab5df. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/ruvector/vector-db.ts:85

  remove(id: string): boolean {
    return this.vectors.delete(id);
  }

  size(): number {
    return this.vectors.size;
  }

  clear(): void {
    this.vectors.clear();
  }
}

/**
 * Compute cosine similarity between two vectors
 */
function cosineSimilarity(a: Float32Array, b: Float32Array): number {
  if (a.length !== b.length) {
    throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
  }

  let dotProduct = 0;
  let normA = 0;
  let normB = 0;

  for (let i = 0; i < a.length; i++) {
    dotProduct += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }

  const denom = Math.sqrt(normA) * Math.sqrt(normB);
  return denom === 0 ? 0 : dotProduct / denom;
}

/**
 * Whether the hash-embedding one-time warning has been emitted

View on GitHub (pinned to fa13ee4ad6)