ruvnet/ruflo · error · Error

SemanticRouter requires a dimension in config

Error message

SemanticRouter requires a dimension in config

What it means

SemanticRouter's constructor requires config.dimension to be a number; it uses it to validate every subsequent embedding length and to size normalization. The guard rejects undefined config, missing dimension, or a dimension that is not typeof 'number' (NaN passes this check because typeof NaN === 'number' — a known gap). The error throws synchronously during construction, before any intent is stored.

Source

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

  dimension: number;
  metric?: 'cosine' | 'euclidean' | 'dotProduct';
}

interface StoredIntent {
  name: string;
  embeddings: Float32Array[];
  metadata: Record<string, unknown>;
}

export class SemanticRouter {
  private dimension: number;
  private metric: 'cosine' | 'euclidean' | 'dotProduct';
  private intents: Map<string, StoredIntent> = new Map();
  private totalVectors = 0;

  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

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Pass a numeric dimension matching your embedding model (e.g., 384 for all-MiniLM-L6-v2, 1536 for text-embedding-ada-002).
2. Also guard against NaN: check Number.isFinite(config.dimension).
3. Load dimension from the embedding backend rather than hardcoding, so it stays in sync.

Example fix

// before
const router = new SemanticRouter({ metric: 'cosine' }); // throws

// after
const DIM = 384; // must match your embedder output
if (!Number.isFinite(DIM)) throw new Error('dimension not configured');
const router = new SemanticRouter({ dimension: DIM, metric: 'cosine' });

function makeRouter(cfg) {
  if (!cfg || !Number.isFinite(cfg.dimension) || cfg.dimension <= 0) {
    throw new Error('SemanticRouter needs a positive finite numeric dimension');
  }
  return new SemanticRouter(cfg);
}

function isRouterConfig(c): c is { dimension: number; metric?: 'cosine' | 'euclidean' | 'dotProduct' } {
  return c != null && typeof c.dimension === 'number' && Number.isFinite(c.dimension) && c.dimension > 0;
}

When it happens

Trigger: Calling `new SemanticRouter({})`, `new SemanticRouter({ metric: 'cosine' })`, `new SemanticRouter(undefined)`, or `new SemanticRouter({ dimension: undefined })`. Also destructuring config from an env-parsed object that omitted dimension.

Common situations: Defaulting config to {} when no options are provided; reading dimension from a model config that did not load; JSON config where 'dimension' was misspelled as 'dimensions'.

Related errors

• Invalid route entry: ${JSON.stringify(r)}
• Duplicate route name: ${r.name}
• MctsExplorer requires at least one peer
• mode must be legacy, observe, or enforce
• Key exceeds maximum nesting depth of ${MAX_NESTING_DEPTH}

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