ruvnet/ruflo · error · Error

Unsupported KV cache version: ${version}

Error message

Unsupported KV cache version: ${version}

What it means

Thrown by loadKvCache when the version u32 (offset 4) does not equal RVKV_VERSION. The RVKV format is versioned; loading a cache written by a different version of the writer is rejected to avoid misinterpreting the layout. Runs after magic check, before entry parsing.

Source

Thrown at v3/@claude-flow/cli/src/appliance/gguf-engine.ts:394

    const header = Buffer.alloc(44);
    header.writeUInt32LE(RVKV_MAGIC, 0);
    header.writeUInt32LE(RVKV_VERSION, 4);
    modelHash.copy(header, 8);
    header.writeUInt32LE(this.kvCache.size, 40);

    await writeFile(path, Buffer.concat([header, entryData, footer]));
    if (this.config.verbose) console.log(`[gguf-engine] KV cache persisted: ${this.kvCache.size} entries`);
  }

  /** Restore KV cache from an RVF-compatible binary file. */
  async loadKvCache(inputPath: string): Promise<void> {
    const data = await readFile(inputPath);
    if (data.length < 44) throw new Error('KV cache file too small');

    const magic = data.readUInt32LE(0);
    if (magic !== RVKV_MAGIC) throw new Error(`Invalid KV cache magic: 0x${magic.toString(16)}`);
    const version = data.readUInt32LE(4);
    if (version !== RVKV_VERSION) throw new Error(`Unsupported KV cache version: ${version}`);

    const entryCount = data.readUInt32LE(40);
    let offset = 44;
    const entries = new Map<string, Buffer>();

    for (let i = 0; i < entryCount; i++) {
      if (offset + 8 > data.length) throw new Error('KV cache file truncated');
      const keyLen = data.readUInt32LE(offset);
      const valLen = data.readUInt32LE(offset + 4);
      offset += 8;
      if (offset + keyLen + valLen > data.length) throw new Error('KV cache file truncated');
      entries.set(data.toString('utf-8', offset, offset + keyLen), Buffer.from(data.subarray(offset + keyLen, offset + keyLen + valLen)));
      offset += keyLen + valLen;
    }

    // Verify footer hash (mandatory)
    if (offset + 32 > data.length) {
      throw new Error('KV cache file missing SHA256 footer');

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Delete the old cache files after an upgrade and regenerate them with the current engine (KV caches are derived data, safe to rebuild).
2. Keep caches version-tagged in their directory names so you can identify and purge stale ones post-upgrade.
3. Treat version mismatch as a cold-start signal rather than a fatal error (wrap loadKvCache and continue without the cache).
4. Pin the engine version if you must preserve caches across runs.

Example fix

// before
await engine.loadKvCache(path);

// after
try {
  await engine.loadKvCache(path);
} catch (e) {
  if (e instanceof Error && /Unsupported KV cache version/.test(e.message)) {
    logger.warn({ path }, 'cache version mismatch; rebuilding');
    await fsUnlink(path).catch(() => {});
  } else throw e;
}

// After an upgrade, purge caches whose version no longer matches:
const fh = await open(path, 'r');
const buf = Buffer.alloc(8);
await fh.read(buf, 0, 8, 0);
await fh.close();
if (buf.readUInt32LE(4) !== RVKV_VERSION) {
  await fsUnlink(path).catch(() => {});
  return; // regenerate
}
await engine.loadKvCache(path);

function isSupportedCacheVersion(v: number): boolean {
  return v === RVKV_VERSION;
}

try {
  await engine.loadKvCache(path);
} catch (e) {
  if (e instanceof Error && /Unsupported KV cache version/.test(e.message)) {
    await fsUnlink(path).catch(() => {});
    return; // rebuild
  }
  throw e;
}

When it happens

Trigger: Loading a KV cache produced by an older or newer build of the engine whose RVKV_VERSION constant differs — e.g. after upgrading the CLI/appliance package, the on-disk caches from the prior version no longer match.

Common situations: Package upgrade that bumped RVKV_VERSION without a migration; caches shared across machines running different engine versions; a downgrade after an upgrade leaves incompatible caches.

Related errors

• Unsupported GGUF version: ${version} (expected 2 or 3)
• No KV cache output path specified
• KV cache file too small
• Invalid KV cache magic: 0x${magic.toString(16)}
• KV cache file truncated

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/11db87323ea87ff4. Report an issue: GitHub.