{"record":{"id":"dc6f00b2faf131f8","repo":"ruvnet/ruflo","slug":"unsupported-rvfa-version-version-expected-r","errorCode":null,"errorMessage":"Unsupported RVFA version: ${version} (expected ${RVFA_VERSION})","messagePattern":"Unsupported RVFA version: (.+?) \\(expected (.+?)\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/rvfa-format.ts","lineNumber":324,"sourceCode":"    this.header = header;\n  }\n\n  /** Parse an RVFA image from an in-memory Buffer. */\n  static fromBuffer(buf: Buffer): RvfaReader {\n    if (buf.length < PREAMBLE_SIZE) {\n      throw new Error('Buffer too small to contain RVFA preamble');\n    }\n\n    // Magic\n    const magic = buf.subarray(0, MAGIC_SIZE).toString('ascii');\n    if (magic !== 'RVFA') {\n      throw new Error(`Invalid RVFA magic: expected \"RVFA\", got \"${magic}\"`);\n    }\n\n    // Version\n    const version = buf.readUInt32LE(MAGIC_SIZE);\n    if (version !== RVFA_VERSION) {\n      throw new Error(\n        `Unsupported RVFA version: ${version} (expected ${RVFA_VERSION})`,\n      );\n    }\n\n    // Header length\n    const headerLen = buf.readUInt32LE(MAGIC_SIZE + VERSION_SIZE);\n    if (headerLen > MAX_HEADER_JSON_SIZE) {\n      throw new Error(\n        `Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADER_JSON_SIZE})`,\n      );\n    }\n    if (PREAMBLE_SIZE + headerLen > buf.length) {\n      throw new Error('Buffer too small to contain declared header');\n    }\n\n    // Parse header JSON\n    const headerSlice = buf.subarray(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLen);\n    let parsed: unknown;","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/rvfa-format.ts#L306-L342","documentation":"Thrown by RvfaReader.fromBuffer() when the u32LE version at offset 4 is not RVFA_VERSION (currently 1). The magic check passed, so the buffer is structurally an RVFA image, but it was produced by an incompatible format revision. The reader refuses to interpret offsets/sections it cannot safely decode.","triggerScenarios":"Parsing an appliance produced by a future RvfaWriter that bumped RVFA_VERSION, or a buffer whose version bytes were corrupted. The magic check already succeeded.","commonSituations":"Cross-version appliance distribution: an older reader receives an appliance from a newer builder, or vice versa; bit-flip corruption of the version field.","solutions":["Regenerate the appliance with a builder whose RVFA_VERSION matches the reader (currently 1).","Upgrade the reading-side library to a version compatible with the appliance's format version.","Verify integrity (run reader.verify()) — if only the version field is wrong but the rest is intact, suspect corruption.","Do not hand-edit the version field; later offsets may follow a different layout."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const EXPECTED_RVFA_VERSION = 1;\nfunction rvfaVersionMatches(buf: Buffer): boolean {\n  return buf.length >= 8 && buf.readUInt32LE(4) === EXPECTED_RVFA_VERSION;\n}","typeGuard":null,"tryCatchPattern":"try {\n  const reader = RvfaReader.fromBuffer(buf);\n} catch (e) {\n  if (/Unsupported RVFA version/.test((e as Error).message)) {\n    throw new Error('Appliance format version is incompatible with this reader; align versions');\n  }\n  throw e;\n}","preventionTips":["Pin the claude-flow/RVFA version on both producer and consumer sides.","When bumping RVFA_VERSION, ship a migration reader alongside it.","Embed the producer version in the header metadata for diagnostics.","Run reader.verify() to distinguish corruption from a genuine version mismatch."],"tags":["rvfa","version","compatibility","binary-format"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}