{"record":{"id":"8dd85ebb5e942853","repo":"ruvnet/ruflo","slug":"header-json-exceeds-maximum-size-headerlen","errorCode":null,"errorMessage":"Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADER_JSON_SIZE})","messagePattern":"Header JSON exceeds maximum size \\((.+?) > (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/rvfa-format.ts","lineNumber":332,"sourceCode":"\n    // Magic\n    const magic = buf.subarray(0, MAGIC_SIZE).toString('ascii');\n    if (magic !== 'RVFA') {\n      throw new Error(`Invalid RVFA magic: expected \"RVFA\", got \"${magic}\"`);\n    }\n\n    // Version\n    const version = buf.readUInt32LE(MAGIC_SIZE);\n    if (version !== RVFA_VERSION) {\n      throw new Error(\n        `Unsupported RVFA version: ${version} (expected ${RVFA_VERSION})`,\n      );\n    }\n\n    // Header length\n    const headerLen = buf.readUInt32LE(MAGIC_SIZE + VERSION_SIZE);\n    if (headerLen > MAX_HEADER_JSON_SIZE) {\n      throw new Error(\n        `Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADER_JSON_SIZE})`,\n      );\n    }\n    if (PREAMBLE_SIZE + headerLen > buf.length) {\n      throw new Error('Buffer too small to contain declared header');\n    }\n\n    // Parse header JSON\n    const headerSlice = buf.subarray(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLen);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(headerSlice.toString('utf-8'));\n    } catch {\n      throw new Error('Failed to parse RVFA header JSON');\n    }\n\n    if (!validateHeader(parsed)) {\n      throw new Error('RVFA header failed validation');","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/rvfa-format.ts#L314-L350","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["For a normal third-party image: re-download it — a >1 MiB declared header on a standard appliance is corruption","If you build images: move bulk metadata out of the header JSON into a payload section via addSection() and rebuild","Confirm producer and consumer agree on MAX_HEADER_JSON_SIZE (same CLI version)"],"exampleFix":"// before — builder stuffs a huge manifest into the header JSON\nheader.manifest = entireFileListing; // JSON blows past the 1 MiB cap\n\n// after — keep the header minimal; ship bulk data as a compressed section\nbuilder.addSection('manifest', Buffer.from(JSON.stringify(entireFileListing)), { compression: 'gzip' });","handlingStrategy":"validation","validationCode":"const headerLen = buf.readUInt32LE(8);\nif (headerLen > 1024 * 1024) {\n  throw new Error('Implausible header length (>1 MiB) — image is corrupt, re-download');\n}\nconst reader = RvfaReader.fromBuffer(buf);","typeGuard":null,"tryCatchPattern":"try {\n  const reader = RvfaReader.fromBuffer(buf);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('exceeds maximum size')) {\n    // either corruption (re-download) or a producer embedding huge metadata (rebuild with addSection)\n  } else {\n    throw e;\n  }\n}","preventionTips":["Keep appliance header JSON minimal (identifiers, versions, hashes); bulk data belongs in payload sections via addSection()","Validate the length word before fromBuffer when handling untrusted or transported images","Fail downloads early on size anomalies so corrupt length words never reach the parser"],"tags":["rvfa-format","rvfa","header","size-limit","input-validation"],"backgroundTag":"header-size-limit-exceeded","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}