{"record":{"id":"fc50495825ce1855","repo":"ruvnet/ruflo","slug":"kv-cache-integrity-check-failed-hash-mismatch","errorCode":null,"errorMessage":"KV cache integrity check failed: hash mismatch","messagePattern":"KV cache integrity check failed: hash mismatch","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":416,"sourceCode":"    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');\n    }\n    const stored = data.subarray(offset, offset + 32);\n    const computed = createHash('sha256').update(data.subarray(44, offset)).digest();\n    if (!stored.equals(computed)) throw new Error('KV cache integrity check failed: hash mismatch');\n\n    this.kvCache = entries;\n    if (this.config.verbose) console.log(`[gguf-engine] KV cache loaded: ${entries.size} entries`);\n  }\n\n  /** Return metadata for all loaded models. */\n  getLoadedModels(): GgufMetadata[] { return Array.from(this.loadedModels.values()); }\n\n  /** Store a key-value pair in the in-memory KV cache. */\n  setKvEntry(key: string, value: Buffer): void { this.kvCache.set(key, value); }\n\n  /** Retrieve a key-value pair from the in-memory KV cache. */\n  getKvEntry(key: string): Buffer | undefined { return this.kvCache.get(key); }\n\n  /** Release resources, unload models, and optionally persist the KV cache. */\n  async shutdown(): Promise<void> {\n    if (this.config.kvCachePath && this.kvCache.size > 0) {\n      try { await this.persistKvCache(this.config.kvCachePath); }","sourceCodeStart":398,"sourceCodeEnd":434,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L398-L434","documentation":"The RVKV format ends with SHA-256 over bytes 44..offset (all entry data); loadKvCache() recomputes it and compares to the stored footer. A mismatch means the file is structurally complete but its content hash differs — silent corruption after write (bit rot, torn write from a concurrent writer) or tampering. This is the integrity check that catches damage errors 120/121 miss.","triggerScenarios":"`engine.loadKvCache(path)` on a structurally valid file where `stored.equals(computed)` is false — e.g. one flipped byte in the entry region, two engine instances writing the same kvCachePath concurrently (interleaved writes), or a transfer channel that mangles bytes (FTP ASCII mode).","commonSituations":"Multiple processes persisting KV caches to one path; failing storage media; manual binary edits; caches copied through a byte-mangling transport.","solutions":["Delete the cache file and let it regenerate — do not attempt repair","Ensure exactly one process/engine instance writes a given kvCachePath","Persist atomically (temp file + rename) to eliminate torn writes","If mismatches persist across fresh regenerations, suspect the storage medium or the transfer channel"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await engine.loadKvCache(kvCachePath);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('KV cache integrity check failed')) {\n    await rm(kvCachePath, { force: true }); // content hash mismatch — drop and rebuild\n  } else {\n    throw err;\n  }\n}","preventionTips":["Allow exactly one writer per kvCachePath to avoid interleaved writes","Persist atomically (temp file + rename) so torn writes cannot pass structural parsing but fail hashing","Verify integrity right after persisting if caches are shipped across machines"],"tags":["gguf-engine","kv-cache","sha256","integrity","checksum"],"backgroundTag":"checksum-verification-failed","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"}