{"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":"Error","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/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L374-L410","documentation":"Thrown by loadKvCache when the first u32 of the cache file is not RVKV_MAGIC. This is the format-identity check for the RVF-compatible KV cache format; a mismatch means the file is not an RVKV cache (e.g. a raw tensor file, a different serializer's output, or random bytes). Runs after the size check.","triggerScenarios":"Loading a file that is large enough but is not an RVKV cache — e.g. a GGUF model file, a pickle, or a JSON dump saved at the same path. Also fires on a partially overwritten file where only the tail changed.","commonSituations":"Reusing a path that previously held another format; a misconfigured cache directory mixing formats; a stale cache from an older bridge version that used a different magic (though version mismatch usually catches that).","solutions":["Confirm the file was produced by persistKvCache of this engine (same RVKV_MAGIC); if not, delete it and regenerate.","Delete the offending file and let the next persistKvCache recreate it cleanly.","Keep KV caches in a dedicated directory keyed by model hash so formats do not collide.","Fall back to a cold cache on magic mismatch instead of propagating the error."],"exampleFix":"// before\nawait engine.loadKvCache(path);\n\n// after\ntry {\n  await engine.loadKvCache(path);\n} catch (e) {\n  if (e instanceof Error && /Invalid KV cache magic/.test(e.message)) {\n    logger.warn({ path }, 'magic mismatch; deleting stale cache');\n    await fsUnlink(path).catch(() => {});\n  } else throw e;\n}","handlingStrategy":"fallback","validationCode":"// Sniff the magic before delegating to loadKvCache:\nconst fh = await open(path, 'r');\nconst head = Buffer.alloc(4);\nawait fh.read(head, 0, 4, 0);\nawait fh.close();\nif (head.readUInt32LE(0) !== RVKV_MAGIC) {\n  await fsUnlink(path).catch(() => {});\n  return; // not an RVKV cache; cold start\n}\nawait engine.loadKvCache(path);","typeGuard":"function isRvkfMagic(buf: Buffer): boolean {\n  return buf.length >= 4 && buf.readUInt32LE(0) === RVKV_MAGIC;\n}","tryCatchPattern":"try {\n  await engine.loadKvCache(path);\n} catch (e) {\n  if (e instanceof Error && /Invalid KV cache magic/.test(e.message)) {\n    await fsUnlink(path).catch(() => {});\n    return;\n  }\n  throw e;\n}","preventionTips":["Keep KV caches in a dedicated directory to avoid format collisions.","Delete and regenerate caches with a foreign magic.","Cold-start on magic mismatch instead of crashing.","Do not reuse paths that held other formats."],"tags":["gguf","kv-cache","integrity","magic-number"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}