What causes "Failed to parse RVFA header JSON" in ruvnet/ruflo?

Regenerate the appliance from a known-good build.

ruvnet/ruflo · error · Error

Failed to parse RVFA header JSON

Error message

Failed to parse RVFA header JSON

What it means

Thrown by RvfaReader.fromBuffer() when JSON.parse fails on the header slice (the bytes between PREAMBLE_SIZE and PREAMBLE_SIZE + headerLen). The framing checks (size, magic, version, header-length sanity) all passed, but the bytes declared as the header are not valid UTF-8 JSON. The original parse error is swallowed and replaced by this generic message.

Source

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

    // 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;
    try {
      parsed = JSON.parse(headerSlice.toString('utf-8'));
    } catch {
      throw new Error('Failed to parse RVFA header JSON');
    }

    if (!validateHeader(parsed)) {
      throw new Error('RVFA header failed validation');
    }
    const header = parsed as RvfaHeader;

    // Bounds-check every section offset
    const totalSize = buf.length;
    for (const sec of header.sections) {
      if (sec.offset < 0 || sec.size < 0) {
        throw new Error(`Section "${sec.id}" has negative offset or size`);
      }
      if (sec.offset + sec.size > totalSize - SHA256_SIZE) {
        throw new Error(
          `Section "${sec.id}" extends beyond buffer ` +
            `(offset=${sec.offset}, size=${sec.size}, bufLen=${totalSize})`,
        );

View on GitHub (pinned to 6b01dc5a68)

Solutions

Regenerate the appliance from a known-good build.
If debugging a custom writer, verify headerLen equals the exact UTF-8 byte length of the JSON.
Dump the header slice (buf.subarray(12, 12+headerLen)) and inspect for non-UTF-8 or truncated JSON.
Treat the file as untrusted/corrupted and re-acquire it.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/Failed to parse RVFA header JSON/.test((e as Error).message)) {
    const hLen = buf.readUInt32LE(8);
    console.error('Header slice:', buf.subarray(12, 12 + hLen).toString('utf-8'));
    throw new Error('Header bytes are not valid JSON; the appliance is corrupt');
  }
  throw e;
}

Prevention

Only use appliances produced by RvfaWriter.build() to guarantee valid header JSON.
If writing a custom producer, ensure headerLen equals the exact UTF-8 byte length of the serialized JSON.
Do not edit appliances in place with a hex editor.
Re-acquire appliances from a known-good source when the header is unparseable.

When it happens

Trigger: Corruption of the header JSON bytes (bit-rot, partial overwrite), non-UTF-8 content in the header region, or a header-length field that points at the wrong slice (off-by-one in a custom writer).

Common situations: Disk corruption; a file spliced together incorrectly; a writer bug that mis-computed headerLen; an appliance that was edited in place with a hex editor.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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