ruvnet/ruflo · error

Header JSON exceeds maximum size

Error message

Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADER_JSON_SIZE})

What it means

The header-length word at offset 8 is checked against MAX_HEADER_JSON_SIZE (1 MiB) before any subarray or JSON.parse happens, to prevent absurd allocations from a corrupted length field. Exceeding it means either the headerLen word is garbage (most common — often after other corruption) or a builder genuinely embedded more than 1 MiB of metadata into the header JSON.

Solutions

1. For a normal third-party image: re-download it — a >1 MiB declared header on a standard appliance is corruption
2. If you build images: move bulk metadata out of the header JSON into a payload section via addSection() and rebuild
3. Confirm producer and consumer agree on MAX_HEADER_JSON_SIZE (same CLI version)

Example fix

// before — builder stuffs a huge manifest into the header JSON
header.manifest = entireFileListing; // JSON blows past the 1 MiB cap

// after — keep the header minimal; ship bulk data as a compressed section
builder.addSection('manifest', Buffer.from(JSON.stringify(entireFileListing)), { compression: 'gzip' });

const headerLen = buf.readUInt32LE(8);
if (headerLen > 1024 * 1024) {
  throw new Error('Implausible header length (>1 MiB) — image is corrupt, re-download');
}
const reader = RvfaReader.fromBuffer(buf);

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (e instanceof Error && e.message.includes('exceeds maximum size')) {
    // either corruption (re-download) or a producer embedding huge metadata (rebuild with addSection)
  } else {
    throw e;
  }
}

When it happens

Trigger: `RvfaReader.fromBuffer(buf)` where readUInt32LE(8) > 1048576 — a bit-flipped or mismatched length word, or an image built with a huge manifest/file listing placed in the header JSON instead of a payload section.

Common situations: Corrupted downloads where the length word is scrambled; producers that stuff entire manifests into the header rather than using addSection payloads; version skew where a newer format allows larger headers than this reader accepts.

Related errors

• Buffer too small to contain RVFA preamble
• Invalid RVFA magic: expected "RVFA", got
• Unsupported RVFA version
• browser/eval: script must not be empty
• Buffer too small for RVFP preamble

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

Appendix: source

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

    // 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;
    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');

View on GitHub (pinned to fa13ee4ad6)