ruvnet/ruflo · error · Error

RVFA header failed validation

Error message

RVFA header failed validation

What it means

Thrown by RvfaReader.fromBuffer() when the header JSON parsed successfully but validateHeader() returned false — the object is missing required fields, has wrong-typed values, or violates the RvfaHeader schema (e.g. profile not in cloud/hybrid/offline, sections not an array, section missing id/offset/size). The validateHeader type-guard encodes the full structural contract.

Source

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

      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})`,
        );
      }
    }

    // Check for overlapping sections

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Regenerate the appliance with RvfaBuilder.build() which emits a schema-conformant header.
2. If interoperating with a custom producer, diff its header object against validateHeader's checks in rvfa-format.ts.
3. Inspect the parsed header fields (dump the JSON) to find which required field is missing or mistyped.
4. Do not patch the header by hand unless you also fix the section offsets and footer SHA256.

import { validateHeader, type RvfaHeader } from './rvfa-format.js';
// validateHeader is exported and is a type guard:
// function validateHeader(header: unknown): header is RvfaHeader;

function parseHeaderSafe(buf: Buffer): RvfaHeader | null {
  const hLen = buf.readUInt32LE(8);
  const parsed = JSON.parse(buf.subarray(12, 12 + hLen).toString('utf-8'));
  return validateHeader(parsed) ? parsed : null;
}

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/RVFA header failed validation/.test((e as Error).message)) {
    const hLen = buf.readUInt32LE(8);
    console.error('Header object:', JSON.parse(buf.subarray(12, 12 + hLen).toString('utf-8')));
    throw new Error('Header is missing required fields or has wrong types; see validateHeader contract');
  }
  throw e;
}

When it happens

Trigger: A header object that is valid JSON but not a valid RvfaHeader: missing magic='RVFA', version<1, missing name/appVersion/arch/platform, profile outside the allowed set, sections array containing objects without id/type/offset/size/sha256/compression, or boot/models sub-objects failing their own checks.

Common situations: A hand-crafted or third-party appliance that omits fields; schema drift between a producer and this reader; a header that was partially mutated; a test fixture that was not fully populated.

Related errors

• Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADE
• Buffer too small to contain RVFA preamble
• Invalid RVFA magic: expected "RVFA", got "${magic}"
• Failed to parse RVFA header JSON
• Section "${sec.id}" has negative offset or size

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