{"record":{"id":"11db87323ea87ff4","repo":"ruvnet/ruflo","slug":"unsupported-kv-cache-version-version","errorCode":null,"errorMessage":"Unsupported KV cache version: ${version}","messagePattern":"Unsupported KV cache version: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":394,"sourceCode":"    const header = Buffer.alloc(44);\n    header.writeUInt32LE(RVKV_MAGIC, 0);\n    header.writeUInt32LE(RVKV_VERSION, 4);\n    modelHash.copy(header, 8);\n    header.writeUInt32LE(this.kvCache.size, 40);\n\n    await writeFile(path, Buffer.concat([header, entryData, footer]));\n    if (this.config.verbose) console.log(`[gguf-engine] KV cache persisted: ${this.kvCache.size} entries`);\n  }\n\n  /** Restore KV cache from an RVF-compatible binary file. */\n  async loadKvCache(inputPath: string): Promise<void> {\n    const data = await readFile(inputPath);\n    if (data.length < 44) throw new Error('KV cache file too small');\n\n    const magic = data.readUInt32LE(0);\n    if (magic !== RVKV_MAGIC) throw new Error(`Invalid KV cache magic: 0x${magic.toString(16)}`);\n    const version = data.readUInt32LE(4);\n    if (version !== RVKV_VERSION) throw new Error(`Unsupported KV cache version: ${version}`);\n\n    const entryCount = data.readUInt32LE(40);\n    let offset = 44;\n    const entries = new Map<string, Buffer>();\n\n    for (let i = 0; i < entryCount; i++) {\n      if (offset + 8 > data.length) throw new Error('KV cache file truncated');\n      const keyLen = data.readUInt32LE(offset);\n      const valLen = data.readUInt32LE(offset + 4);\n      offset += 8;\n      if (offset + keyLen + valLen > data.length) throw new Error('KV cache file truncated');\n      entries.set(data.toString('utf-8', offset, offset + keyLen), Buffer.from(data.subarray(offset + keyLen, offset + keyLen + valLen)));\n      offset += keyLen + valLen;\n    }\n\n    // Verify footer hash (mandatory)\n    if (offset + 32 > data.length) {\n      throw new Error('KV cache file missing SHA256 footer');","sourceCodeStart":376,"sourceCodeEnd":412,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L376-L412","documentation":"Bytes 4-8 of the cache file hold the format version, and only RVKV_VERSION (currently 1) is accepted; anything else throws. The cache was written by an engine build with a different RVKV layout, so its entries cannot be trusted and loading stops rather than misreading the structure.","triggerScenarios":"Loading a cache persisted by a different @claude-flow/cli version after an upgrade or downgrade; hand-crafted cache files; caches left in a shared volume by a previous deployment.","commonSituations":"Rolling upgrades across a format change; pinned older CLI images reading newer caches; volume mounts reused between appliance generations.","solutions":["Delete the stale cache and re-persist with the current engine — KV caches are rebuildable by design","Pin one CLI version across nodes that share a cache volume, or namespace cache paths per version","Catch the error and fall back to a cold cache instead of failing generation"],"exampleFix":"// before\nawait engine.loadKvCache(cachePath);\n\n// after\ntry {\n  await engine.loadKvCache(cachePath);\n} catch {\n  await rm(cachePath, { force: true });\n  await engine.persistKvCache(cachePath); // rebuild cold\n}","handlingStrategy":"fallback","validationCode":"const fh = await open(cachePath, 'r');\nconst b = Buffer.alloc(8);\nawait fh.read(b, 0, 8, 0); await fh.close();\nconst version = b.readUInt32LE(4);\nif (b.toString('ascii', 0, 4) !== 'RVKV' || version !== 1) {\n  await engine.persistKvCache(cachePath); // rebuild cold cache\n} else {\n  await engine.loadKvCache(cachePath);\n}","typeGuard":null,"tryCatchPattern":"try { await engine.loadKvCache(cachePath); }\ncatch (e) {\n  if (e instanceof Error && e.message.includes('Unsupported KV cache version')) {\n    await rm(cachePath, { force: true });\n    await engine.persistKvCache(cachePath); // cold start\n  } else throw e;\n}","preventionTips":["Namespace cache paths by CLI/engine version on shared volumes","Treat an unreadable cache as a cold start, never a fatal error","Delete stale caches as part of upgrade/runbook steps"],"tags":["kv-cache","version-mismatch","file-format","nodejs"],"backgroundTag":"unsupported-file-version","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"}