ruvnet/ruflo · error · Error

Failed to parse RVFA header JSON

Error message

Failed to parse RVFA header JSON

What it means

Thrown when the header region declared by the preamble is not valid JSON. The framing is intact but the header payload itself is malformed or in a different serialization.

Source

Thrown at v3/@claude-flow/cli/src/appliance/rvfa-signing.ts:191

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

  const headerLen = buf.readUInt32LE(8);
  const headerStart = PREAMBLE_SIZE;
  const headerEnd = headerStart + headerLen;

  if (headerEnd > buf.length - SHA256_SIZE) {
    throw new Error('Header length extends beyond buffer');
  }

  const headerJson = buf.subarray(headerStart, headerEnd).toString('utf-8');
  let header: Record<string, unknown>;
  try {
    header = JSON.parse(headerJson) as Record<string, unknown>;
  } catch {
    throw new Error('Failed to parse RVFA header JSON');
  }

  const footer = buf.subarray(buf.length - SHA256_SIZE);
  const sectionData = buf.subarray(headerEnd, buf.length - SHA256_SIZE);

  return { header, headerStart, headerEnd, sectionData, footer };
}

/**
 * Compute the signing digest for an RVFA file.
 *
 * The digest is SHA256 of: canonical_header_json (without signature field)
 *                         + section_data_bytes
 *                         + footer_32_bytes
 */
function computeSigningDigest(
  header: Record<string, unknown>,
  sectionData: Buffer,

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Confirm writer and reader share the same RVFA version (JSON header).
2. Re-build the image with a known-good writer.
3. Inspect the header bytes to confirm UTF-8 JSON content.

const headerJson = buf.subarray(headerStart, headerEnd).toString('utf-8');
try {
  JSON.parse(headerJson);
} catch {
  throw new Error('RVFA header region is not valid UTF-8 JSON; check writer version');
}

When it happens

Trigger: headerLen is consistent with the file but the bytes between headerStart and headerEnd fail JSON.parse: encoding mismatch (UTF-16 vs UTF-8), truncation within the header, or a writer that emits a binary header.

Common situations: Writer and reader use different RVFA header formats; header partially overwritten; writer version skew.

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

• Header length extends beyond buffer
• RVFP header magic mismatch
• Failed to parse RVFA header JSON
• Routes config must be a flat array of routes
• KV cache file too small

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