{"record":{"id":"b5c4e2d01fc78e81","repo":"ruvnet/ruflo","slug":"ruvllmconfig-modelsdir-is-required","errorCode":null,"errorMessage":"RuvllmConfig.modelsDir is required","messagePattern":"RuvllmConfig\\.modelsDir is required","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts","lineNumber":135,"sourceCode":"    if (LOW.has(w)) score -= 0.1;\n  }\n  return Math.max(0, Math.min(1, score + Math.min(0.2, words.length / 200)));\n}\n\n// ── Bridge ──────────────────────────────────────────────────\n\nexport class RuvllmBridge {\n  private config: Required<RuvllmConfig>;\n  private models: Map<string, ModelInfo> = new Map();\n  private activeModel: string | null = null;\n  private kvCacheEntries = 0;\n  private ruvectorCore: any = null;\n  private ruvectorRouter: any = null;\n  private ruvectorSona: any = null;\n  private ggufEngine: GgufEngineType | null = null;\n\n  constructor(config: RuvllmConfig) {\n    if (!config.modelsDir) throw new Error('RuvllmConfig.modelsDir is required');\n    this.config = { ...DEFAULT_CONFIG, ...config };\n  }\n\n  /** Probe optional @ruvector packages, initialize GGUF engine, and scan modelsDir. */\n  async initialize(): Promise<void> {\n    this.ruvectorCore = await this.tryImport('@ruvector/core');\n    this.ruvectorRouter = await this.tryImport('@ruvector/router');\n    this.ruvectorSona = await this.tryImport('@ruvector/sona');\n\n    // Initialize GGUF engine for local model inference\n    try {\n      const { GgufEngine } = await import('./gguf-engine.js');\n      this.ggufEngine = new GgufEngine({\n        contextSize: this.config.contextSize,\n        maxTokens: this.config.maxTokens,\n        temperature: this.config.temperature,\n        kvCachePath: this.config.kvCachePath,\n        verbose: this.config.verbose,","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/ruvllm-bridge.ts#L117-L153","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide a modelsDir in the config, e.g. new RuvllmBridge({ modelsDir: '/var/ruv/models' }).","Read modelsDir from an env var with a sensible default: process.env.RUV_MODELS_DIR ?? './models'.","Validate config has modelsDir (a non-empty string pointing to an existing directory) before constructing the bridge.","Ensure the directory exists and is readable so initialize()'s scan does not fail next."],"exampleFix":"// before\nconst bridge = new RuvllmBridge({ contextSize: 4096 });\n\n// after\nconst modelsDir = process.env.RUV_MODELS_DIR;\nif (!modelsDir) throw new Error('RUV_MODELS_DIR must be set');\nconst bridge = new RuvllmBridge({ modelsDir, contextSize: 4096 });","handlingStrategy":"validation","validationCode":"const modelsDir = process.env.RUV_MODELS_DIR;\nif (!modelsDir) throw new Error('RUV_MODELS_DIR must be set');\nconst bridge = new RuvllmBridge({ modelsDir });","typeGuard":"function hasModelsDir(c: RuvllmConfig): c is RuvllmConfig & { modelsDir: string } {\n  return typeof c.modelsDir === 'string' && c.modelsDir.length > 0;\n}","tryCatchPattern":"try {\n  return new RuvllmBridge(config);\n} catch (e) {\n  if (e instanceof Error && /modelsDir is required/.test(e.message)) {\n    throw new Error('Set RUV_MODELS_DIR before starting ruvLLM');\n  }\n  throw e;\n}","preventionTips":["Set RUV_MODELS_DIR (or equivalent) with a default at bootstrap.","Validate config has a non-empty modelsDir pointing to an existing dir.","Fail fast at startup rather than deep in initialize().","Document modelsDir as the one required config field."],"tags":["ruvllm","config","bootstrap","appliance"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}