{"record":{"id":"5f8ec3d6591ed24b","repo":"ruvnet/ruflo","slug":"no-kv-cache-output-path-specified","errorCode":null,"errorMessage":"No KV cache output path specified","messagePattern":"No KV cache output path specified","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":362,"sourceCode":"            if (typeof chunk === 'string') yield chunk;\n            else if (chunk?.text) yield chunk.text;\n          }\n          return;\n        }\n      } catch { /* fall through to single-chunk fallback */ }\n    }\n    const response = await this.generate(request);\n    yield response.text;\n  }\n\n  /**\n   * Persist the KV cache to an RVF-compatible binary file.\n   * Format: RVKV magic | version u32 | model SHA-256 (32B) | entry count u32\n   *         entries: [key_len u32, key, val_len u32, val] | footer SHA-256 (32B)\n   */\n  async persistKvCache(outputPath: string): Promise<void> {\n    const path = outputPath || this.config.kvCachePath;\n    if (!path) throw new Error('No KV cache output path specified');\n\n    const modelHash = createHash('sha256').update(this.activeModelPath ?? 'no-model').digest();\n    const entryBufs: Buffer[] = [];\n    for (const [key, value] of this.kvCache) {\n      const keyBuf = Buffer.from(key, 'utf-8');\n      const hdr = Buffer.alloc(8);\n      hdr.writeUInt32LE(keyBuf.length, 0);\n      hdr.writeUInt32LE(value.length, 4);\n      entryBufs.push(hdr, keyBuf, value);\n    }\n    const entryData = Buffer.concat(entryBufs);\n    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);","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L344-L380","documentation":"Thrown by persistKvCache when both the outputPath argument and this.config.kvCachePath are falsy. The persistence format (RVKV magic | version | model SHA-256 | entries | footer SHA-256) requires a destination file; with no path there is nowhere to write.","triggerScenarios":"Calling persistKvCache() (no argument) on a bridge/engine whose config never set kvCachePath, or calling persistKvCache('') with an empty string. The fallback `outputPath || this.config.kvCachePath` resolves to undefined/empty.","commonSituations":"Default config object omits kvCachePath (it is optional); a caller that constructs the bridge for inference only and later tries to snapshot the KV cache without specifying where; programmatic use that passes undefined instead of a concrete path.","solutions":["Pass an explicit output path: await persistKvCache('/var/ruv/kvcache.rvkv').","Set config.kvCachePath at construction time so persistKvCache() has a default.","Validate the path is a non-empty string before calling, and ensure the parent directory exists and is writable.","If persistence is optional in your flow, guard the call behind a check that a path was configured."],"exampleFix":"// before\nawait engine.persistKvCache();\n\n// after\nconst out = outputPath ?? config.kvCachePath;\nif (!out) throw new Error('configure kvCachePath or pass an output path');\nawait fs.mkdir(dirname(out), { recursive: true });\nawait engine.persistKvCache(out);","handlingStrategy":"validation","validationCode":"const out = outputPath ?? config.kvCachePath;\nif (!out || typeof out !== 'string') {\n  throw new Error('configure kvCachePath or pass an output path to persistKvCache');\n}\nawait engine.persistKvCache(out);","typeGuard":"function hasKvCachePath(p: string | undefined | null): p is string {\n  return typeof p === 'string' && p.length > 0;\n}","tryCatchPattern":"try {\n  await engine.persistKvCache(outputPath);\n} catch (e) {\n  if (e instanceof Error && /No KV cache output path/.test(e.message)) {\n    throw new Error('must configure kvCachePath');\n  }\n  throw e;\n}","preventionTips":["Always pass an explicit path or set config.kvCachePath.","Ensure the parent directory exists and is writable.","Treat kvCachePath as required when persistence is enabled.","Validate the path is a non-empty string before calling."],"tags":["gguf","kv-cache","config","appliance"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}