ruvnet/ruflo · error

Vector dimensions must match

Error message

Vector dimensions must match

What it means

cosineSimilarity() is the private kernel behind search(); it throws when its two vectors differ in length. In practice you see this message from search(query) when the query vector's length differs from the stored vectors' dimensions — search() itself performs no query-length pre-check, so the kernel rejects it mid-iteration. Stored vectors cannot cause it (store() already enforces config.dimensions), so the query is always the odd one out.

Source

Thrown at v3/@claude-flow/plugins/src/integrations/agentic-flow.ts:690

    memoryUsage: number;
  } {
    const vectorSize = (this.config.dimensions ?? 1536) * 4; // 4 bytes per float32
    const memoryUsage = this.vectors.size * vectorSize;

    return {
      vectorCount: this.vectors.size,
      dimensions: this.config.dimensions ?? 1536,
      indexType: this.config.indexType ?? 'hnsw',
      memoryUsage,
    };
  }

  /**
   * Calculate cosine similarity between two vectors.
   */
  private cosineSimilarity(a: Float32Array, b: Float32Array): number {
    if (a.length !== b.length) {
      throw new Error('Vector dimensions must match');
    }

    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 magnitude = Math.sqrt(normA) * Math.sqrt(normB);
    if (magnitude === 0) return 0;

    return dotProduct / magnitude;
  }
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Build queries with the exact same embedding function/model used for stored vectors
2. Pre-check query.length against the store's configured dimensions before calling search()
3. Centralize embedding in one helper used by both the store and search paths so dimensions cannot diverge

Example fix

// before
const hits = await db.search(embedSmall(queryText)); // 384-dim vs 1536-dim store → throws

// after
const dims = 1536;
const q = embed1536(queryText); // same model as indexing
if (q.length !== dims) throw new RangeError(`query is ${q.length}d, index expects ${dims}d`);
const hits = await db.search(q);

const DIMS = 1536; // dimensions the store was initialized with
const q = embed(queryText);
if (q.length !== DIMS) {
  throw new RangeError(`query is ${q.length}d; index expects ${DIMS}d — wrong embedder?`);
}
const hits = await db.search(q);

When it happens

Trigger: Searching with an embedding produced by a different model or dimensionality than the store was initialized with; passing a padded/truncated or empty Float32Array as the query; reusing a query builder configured for another index.

Common situations: Switching embedding models so query-time and index-time embedders diverge; multiple embed functions in the codebase (one per feature) drifting in dimensions; hardcoded example vectors pasted into query code.

Related errors

• Vector dimension mismatch: expected ${this.config.dimensions
• embedding failed
• each record requires a non-empty numeric vector
• vector must be a non-empty numeric array
• AgentDB not initialized

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