{"record":{"id":"705f5458d8beebc2","repo":"ruvnet/ruflo","slug":"invalid-kv-cache-magic-0x-magic-tostring-16","errorCode":null,"errorMessage":"Invalid KV cache magic: 0x${magic.toString(16)}","messagePattern":"Invalid KV cache magic: 0x(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":392,"sourceCode":"    const footer = createHash('sha256').update(entryData).digest();\n\n    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)","sourceCodeStart":374,"sourceCodeEnd":410,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L374-L410","documentation":"The first u32 of an RVF KV cache file must equal RVKV_MAGIC (0x564B5652, ASCII 'RVKV' little-endian); a different value throws. The bytes at inputPath are not an RVF KV cache — typically a model file or unrelated binary/text data passed as a cache.","triggerScenarios":"loadKvCache(modelPath) where a .gguf model was given as the cache path; a cache directory shared with another engine's format; a corrupted or empty-but-sized file.","commonSituations":"Config wiring that swaps model and cache path values; caches from a different appliance version using another format; leftover files with the same extension.","solutions":["Ensure loadKvCache only receives files produced by persistKvCache","Check the first 4 bytes read 'RVKV' before loading; otherwise regenerate the cache","Keep caches in a dedicated directory with a distinctive extension so they cannot be confused with models"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const fh = await open(cachePath, 'r');\nconst b = Buffer.alloc(4);\nawait fh.read(b, 0, 4, 0); await fh.close();\nif (b.toString('ascii') !== 'RVKV') throw new Error('not an RVF KV cache');\nawait engine.loadKvCache(cachePath);","typeGuard":"async function isRvkvCache(path: string): Promise<boolean> {\n  const fh = await open(path, 'r');\n  const b = Buffer.alloc(4);\n  const { bytesRead } = await fh.read(b, 0, 4, 0);\n  await fh.close();\n  return bytesRead === 4 && b.toString('ascii') === 'RVKV';\n}","tryCatchPattern":"try { await engine.loadKvCache(cachePath); }\ncatch (e) { if (e instanceof Error && e.message.includes('Invalid KV cache magic')) { await engine.persistKvCache(cachePath); } else throw e; }","preventionTips":["Use distinct directories/extensions for model files vs cache files","Only feed loadKvCache files that persistKvCache produced","Smoke-check magic bytes when caches arrive from shared volumes"],"tags":["kv-cache","magic-bytes","file-format","nodejs"],"backgroundTag":"invalid-file-magic","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"}