What causes "Must provide name and embeddings array" in ruvnet/ruflo?

Ensure name is a non-empty string (validate before the call).

ruvnet/ruflo · error · Error

Must provide name and embeddings array

Error message

Must provide name and embeddings array

What it means

addIntentWithEmbeddings requires a truthy name and an Array instance for embeddings. The check `!name || !Array.isArray(embeddings)` throws before any embedding is validated or stored, so partial normalization never happens. An empty-string name and a null/undefined embeddings list both trip it.

Source

Thrown at v3/@claude-flow/cli/src/ruvector/semantic-router.ts:56

  constructor(config: RouterConfig) {
    if (!config || typeof config.dimension !== 'number') {
      throw new Error('SemanticRouter requires a dimension in config');
    }
    this.dimension = config.dimension;
    this.metric = config.metric ?? 'cosine';
  }

  /**
   * Add an intent with pre-computed embeddings
   */
  addIntentWithEmbeddings(
    name: string,
    embeddings: Float32Array[],
    metadata: Record<string, unknown> = {}
  ): void {
    if (!name || !Array.isArray(embeddings)) {
      throw new Error('Must provide name and embeddings array');
    }

    // Validate embeddings
    for (const emb of embeddings) {
      if (!(emb instanceof Float32Array) || emb.length !== this.dimension) {
        throw new Error(`Embedding must be Float32Array of length ${this.dimension}`);
      }
    }

    // Normalize embeddings for cosine similarity
    const normalizedEmbeddings = embeddings.map(emb => this.normalize(emb));

    this.intents.set(name, {
      name,
      embeddings: normalizedEmbeddings,
      metadata,
    });
    this.totalVectors += embeddings.length;

View on GitHub (pinned to 6b01dc5a68)

Solutions

Ensure name is a non-empty string (validate before the call).
Pass embeddings as a plain Array (wrap typed arrays with Array.from(...) if needed).
Skip or log intents with missing embeddings rather than forwarding them.

Example fix

// before
router.addIntentWithEmbeddings(intent.name, intent.embs); // throws if name ''

// after
if (!intent.name || !Array.isArray(intent.embs) || intent.embs.length === 0) {
  continue; // or throw a clearer caller-side error
}
router.addIntentWithEmbeddings(intent.name, intent.embs, intent.meta);

Defensive patterns

Strategy: validation

Validate before calling

function addIntentSafe(router, name, embeddings, metadata = {}) {
  if (typeof name !== 'string' || name.length === 0) throw new Error('intent name required');
  if (!Array.isArray(embeddings) || embeddings.length === 0) throw new Error('non-empty embeddings array required');
  router.addIntentWithEmbeddings(name, embeddings, metadata);
}

Type guard

function isIntentInput(n: unknown, e: unknown): n is string {
  return typeof n === 'string' && n.length > 0 && Array.isArray(e) && e.length > 0;
}

Prevention

Validate name and embeddings shape at the producer side before batching.
Wrap typed arrays with Array.from if your pipeline stores Float32Array.
Skip or log empty intents rather than forwarding them to the router.

When it happens

Trigger: Calling addIntentWithEmbeddings('', [...]) with an empty intent name; passing embeddings as a Float32Array instead of an Array (Array.isArray(Float32Array) === false); calling with embeddings=undefined when the caller forgot to compute them.

Common situations: Looping over an object of intents where one key is empty; treating a typed array as an array; refactoring that changed the embeddings parameter type without updating the call site.

Related errors

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/989141eb4b25b56d. Report an issue: GitHub.