ruvnet/ruflo · error · Error

Unsupported RVFA version: ${version} (expected ${RVFA_VERSIO

Error message

Unsupported RVFA version: ${version} (expected ${RVFA_VERSION})

What it means

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.

Source

Thrown at v3/@claude-flow/cli/src/appliance/rvfa-format.ts:324

    this.header = header;
  }

  /** Parse an RVFA image from an in-memory Buffer. */
  static fromBuffer(buf: Buffer): RvfaReader {
    if (buf.length < PREAMBLE_SIZE) {
      throw new Error('Buffer too small to contain RVFA preamble');
    }

    // Magic
    const magic = buf.subarray(0, MAGIC_SIZE).toString('ascii');
    if (magic !== 'RVFA') {
      throw new Error(`Invalid RVFA magic: expected "RVFA", got "${magic}"`);
    }

    // Version
    const version = buf.readUInt32LE(MAGIC_SIZE);
    if (version !== RVFA_VERSION) {
      throw new Error(
        `Unsupported RVFA version: ${version} (expected ${RVFA_VERSION})`,
      );
    }

    // Header length
    const headerLen = buf.readUInt32LE(MAGIC_SIZE + VERSION_SIZE);
    if (headerLen > MAX_HEADER_JSON_SIZE) {
      throw new Error(
        `Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADER_JSON_SIZE})`,
      );
    }
    if (PREAMBLE_SIZE + headerLen > buf.length) {
      throw new Error('Buffer too small to contain declared header');
    }

    // Parse header JSON
    const headerSlice = buf.subarray(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLen);
    let parsed: unknown;

View on GitHub (pinned to 6b01dc5a68)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

const EXPECTED_RVFA_VERSION = 1;
function rvfaVersionMatches(buf: Buffer): boolean {
  return buf.length >= 8 && buf.readUInt32LE(4) === EXPECTED_RVFA_VERSION;
}

Try / catch

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/Unsupported RVFA version/.test((e as Error).message)) {
    throw new Error('Appliance format version is incompatible with this reader; align versions');
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: Cross-version appliance distribution: an older reader receives an appliance from a newer builder, or vice versa; bit-flip corruption of the version field.

Related errors

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