{"record":{"id":"8c4e647b4edc97fe","repo":"ruvnet/ruflo","slug":"dimension-is-required-when-creating-a-new-memory-f","errorCode":null,"errorMessage":"dimension is required when creating a new memory file","messagePattern":"dimension is required when creating a new memory file","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts","lineNumber":110,"sourceCode":"  }\n  return label;\n}\n\n/**\n * Open (or create) a memory file, restoring its COW chain from the lineage\n * manifest when one exists. When neither the `.rvf` nor the manifest exists,\n * `dimension` is required to create a fresh base.\n */\nexport async function openWithLineage(api: AgenticowApi, file: string, dimension?: number) {\n  const manifest = manifestFor(file);\n  if (existsSync(manifest)) {\n    return (api.AgenticMemory as any).load(manifest);\n  }\n  const opts: any = {};\n  if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {\n    opts.dimension = dimension;\n  } else if (!existsSync(file)) {\n    throw new Error('dimension is required when creating a new memory file');\n  }\n  return api.open(file, opts);\n}\n","sourceCodeStart":92,"sourceCodeEnd":114,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts#L92-L114","documentation":"Thrown by openWithLineage() when neither a lineage manifest nor the target `.rvf` file exists AND no integer `dimension` was supplied. Creating a fresh agenticow memory file requires a vector dimension (it sizes the HNSW/base index), so omitting it on a new file is ambiguous. When the file or manifest already exists, dimension is optional because it is read from the existing base.","triggerScenarios":"First-time open of a new memory path without passing dimension; passing dimension as undefined/0/a non-integer; passing dimension as a string; the manifest file was deleted but the data file was expected to exist.","commonSituations":"Integrator called open without dimension on a fresh install; a fixture that expects a pre-existing file but runs in a clean tmpdir; a refactor that stopped forwarding dimension.","solutions":["Pass an integer dimension when opening a path that may not exist yet: e.g. `dimension: 384` (all-MiniLM-L6-v2) or your model's dim.","If you expect the file to exist, ensure the path is correct and the manifest is present alongside the `.rvf`.","Validate dimension in your caller: `Number.isInteger(d) && d > 0` before open."],"exampleFix":"// before — new file, no dimension\nawait openWithLineage(api, '.agenticow/m.rvf'); // throws\n// after\nawait openWithLineage(api, '.agenticow/m.rvf', 384);","handlingStrategy":"validation","validationCode":"function requireDimensionForNewFile(file: string, dim?: number): number {\n  if (Number.isInteger(dim) && (dim as number) > 0) return dim as number;\n  if (!existsSync(file)) throw new Error('dimension is required to create a new memory file');\n  return 0; // existing file — dimension read from base\n}","typeGuard":"const isPositiveInt = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v) && v > 0;","tryCatchPattern":"null","preventionTips":["Always pass the model's vector dimension when opening a path that may be new.","Constant-ize the dimension (e.g. DIM_ALL_MINILM = 384) so it is not a magic number.","Assert the file exists OR dimension is set, in your caller, before open."],"tags":["validation","agenticow","dimension","cow","init"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}