ruvnet/ruflo · error · Error

RuvllmConfig.modelsDir is required

Error message

RuvllmConfig.modelsDir is required

What it means

Thrown by the RuvllmBridge constructor when config.modelsDir is falsy. modelsDir is the only required field of RuvllmConfig — it tells the bridge where to discover GGUF models during initialize(). Without it the bridge cannot scan for or load models, so construction is rejected before any I/O.

Source

Thrown at v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts:135

    if (LOW.has(w)) score -= 0.1;
  }
  return Math.max(0, Math.min(1, score + Math.min(0.2, words.length / 200)));
}

// ── Bridge ──────────────────────────────────────────────────

export class RuvllmBridge {
  private config: Required<RuvllmConfig>;
  private models: Map<string, ModelInfo> = new Map();
  private activeModel: string | null = null;
  private kvCacheEntries = 0;
  private ruvectorCore: any = null;
  private ruvectorRouter: any = null;
  private ruvectorSona: any = null;
  private ggufEngine: GgufEngineType | null = null;

  constructor(config: RuvllmConfig) {
    if (!config.modelsDir) throw new Error('RuvllmConfig.modelsDir is required');
    this.config = { ...DEFAULT_CONFIG, ...config };
  }

  /** Probe optional @ruvector packages, initialize GGUF engine, and scan modelsDir. */
  async initialize(): Promise<void> {
    this.ruvectorCore = await this.tryImport('@ruvector/core');
    this.ruvectorRouter = await this.tryImport('@ruvector/router');
    this.ruvectorSona = await this.tryImport('@ruvector/sona');

    // Initialize GGUF engine for local model inference
    try {
      const { GgufEngine } = await import('./gguf-engine.js');
      this.ggufEngine = new GgufEngine({
        contextSize: this.config.contextSize,
        maxTokens: this.config.maxTokens,
        temperature: this.config.temperature,
        kvCachePath: this.config.kvCachePath,
        verbose: this.config.verbose,

View on GitHub (pinned to 6b01dc5a68)

Solutions

  1. Provide a modelsDir in the config, e.g. new RuvllmBridge({ modelsDir: '/var/ruv/models' }).
  2. Read modelsDir from an env var with a sensible default: process.env.RUV_MODELS_DIR ?? './models'.
  3. Validate config has modelsDir (a non-empty string pointing to an existing directory) before constructing the bridge.
  4. Ensure the directory exists and is readable so initialize()'s scan does not fail next.

Example fix

// before
const bridge = new RuvllmBridge({ contextSize: 4096 });

// after
const modelsDir = process.env.RUV_MODELS_DIR;
if (!modelsDir) throw new Error('RUV_MODELS_DIR must be set');
const bridge = new RuvllmBridge({ modelsDir, contextSize: 4096 });
Defensive patterns

Strategy: validation

Validate before calling

const modelsDir = process.env.RUV_MODELS_DIR;
if (!modelsDir) throw new Error('RUV_MODELS_DIR must be set');
const bridge = new RuvllmBridge({ modelsDir });

Type guard

function hasModelsDir(c: RuvllmConfig): c is RuvllmConfig & { modelsDir: string } {
  return typeof c.modelsDir === 'string' && c.modelsDir.length > 0;
}

Try / catch

try {
  return new RuvllmBridge(config);
} catch (e) {
  if (e instanceof Error && /modelsDir is required/.test(e.message)) {
    throw new Error('Set RUV_MODELS_DIR before starting ruvLLM');
  }
  throw e;
}

Prevention

When it happens

Trigger: Constructing `new RuvllmBridge({})` or `new RuvllmBridge({ contextSize: 4096 })` — any config object lacking a truthy modelsDir. Also via getRuvllmBridge(config) with a config missing modelsDir on first call.

Common situations: Loading the bridge config from environment variables without defaults (RUV_MODELS_DIR unset); a config file that omits modelsDir; passing an empty object during early bootstrap. Other fields (contextSize etc.) fall back to DEFAULT_CONFIG, but modelsDir has no default by design.

Related errors

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