Unsupported RVFA version

Error message

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

What it means

The u32 LE version word at offset 4 must equal RVFA_VERSION (currently 1). Any other value is an image written by a different @claude-flow/cli release (or a corrupted version word), and the parser refuses to guess the layout of an unknown version. The message includes both the found and expected numbers.

Solutions

Upgrade the reading CLI to the version that produced the image (the message states both versions)
Or rebuild the appliance locally with the current version so producer and consumer match
If both sides claim version 1, suspect bit corruption — re-fetch the image

Example fix

// before
const reader = RvfaReader.fromBuffer(buf); // Unsupported RVFA version: 2 (expected 1)

// after
const ver = buf.readUInt32LE(4);
if (ver !== 1) throw new Error(`Image format v${ver} needs a matching CLI — upgrade @claude-flow/cli`);
const reader = RvfaReader.fromBuffer(buf);

Defensive patterns

Strategy: validation

Validate before calling

const version = buf.readUInt32LE(4);
if (version !== 1) { // RVFA_VERSION
  throw new Error(`Appliance format v${version} not supported by this CLI — upgrade or rebuild`);
}
const reader = RvfaReader.fromBuffer(buf);

Try / catch

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/Unsupported RVFA version/.test(String(e))) {
    // producer/consumer version skew — upgrade the CLI or rebuild the image
  } else {
    throw e;
  }
}

Prevention

Pin the same @claude-flow/cli version across fleets that produce and consume appliance images
Gate on the version word read straight from the file before committing to a parse

When it happens

Trigger: `RvfaReader.fromBuffer(buf)` on an appliance image produced by a newer/older CLI with a different RVFA_VERSION; corruption in bytes 4–7 (usually preceded by a magic failure); stale IPFS-published images read after a format bump.

Common situations: Mixed-version fleets sharing appliance images; pulling an old appliance CID with an upgraded CLI (or vice versa); rebuilding images without regenerating downstream caches.

Related errors

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

Appendix: 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 fa13ee4ad6)