{"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":"exception","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/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts#L92-L114","documentation":"Thrown by openWithLineage() (agenticow-loader.ts:110) when none of the three ways to size a memory file is available: no <file>.agenticow.json lineage manifest exists, the .rvf data file itself does not exist, and the dimension argument is not a positive integer. A fresh agenticow HNSW store cannot be created without knowing its vector dimension, so creation is refused rather than guessed.","triggerScenarios":"agenticow_query against a path that was never created — the query tool calls openWithLineage(api, path) with NO dimension, so any mistyped or missing path always looks like a new file and hits this. Also agenticow_ingest on a fresh path with dimension omitted, 0, negative, non-integer (384.5), or passed as a string ('384') — the guard requires typeof number && Number.isInteger && > 0.","commonSituations":"Querying before the first ingest; a path typo so the tool looks for a file that does not exist; dimension sent as a string through a generic JSON pipeline; assuming the store auto-detects dimension from the first vector when dimension is actually required up front.","solutions":["Create the file first with agenticow_ingest and an explicit positive integer dimension matching your embedding model (e.g. 384 for all-MiniLM-L6-v2, 1536 for text-embedding-3-small)","Double-check the path spelling — a wrong path is indistinguishable from a new file and triggers this on query","Pass dimension as a JSON integer, not a string or float"],"exampleFix":"// before: query on a not-yet-created file\nawait callTool('agenticow_query', { path: 'memory/main.rvf', vector: v });\n// throws: dimension is required when creating a new memory file\n\n// after: create with explicit dimension first\nawait callTool('agenticow_ingest', { path: 'memory/main.rvf', dimension: 384, records: [{ vector: v, text: 'seed' }] });\nawait callTool('agenticow_query', { path: 'memory/main.rvf', vector: q });","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nconst dim = 384; // your embedding model's dimension\n// safe to omit dimension only when the file already exists\nconst needsDim = !existsSync(file) && !existsSync(`${file}.agenticow.json`);\nif (needsDim && !(Number.isInteger(dim) && dim > 0)) {\n  throw new Error('pass a positive integer dimension to create the store');\n}","typeGuard":"const isPositiveInt = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v) && v > 0;","tryCatchPattern":"try {\n  await callTool('agenticow_query', { path, vector });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('dimension is required')) {\n    // wrong path or uninitialized store: create it explicitly first\n    await callTool('agenticow_ingest', { path, dimension: 384, records: seed });\n    return callTool('agenticow_query', { path, vector });\n  }\n  throw e;\n}","preventionTips":["Bootstrap every memory file with one explicit-dimension ingest before any query tooling runs","Centralize the dimension constant next to your embedding model choice so they can never drift","A wrong path looks exactly like a new file — verify paths exist before querying"],"tags":["validation","agenticow","memory","vector-dimension","initialization"],"backgroundTag":"missing-vector-dimension","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}