{"record":{"id":"9c797f5729cbc5ad","repo":"ruvnet/ruflo","slug":"rvfa-header-failed-validation","errorCode":null,"errorMessage":"RVFA header failed validation","messagePattern":"RVFA header failed validation","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/rvfa-format.ts","lineNumber":350,"sourceCode":"      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');\n    }\n    const header = parsed as RvfaHeader;\n\n    // Bounds-check every section offset\n    const totalSize = buf.length;\n    for (const sec of header.sections) {\n      if (sec.offset < 0 || sec.size < 0) {\n        throw new Error(`Section \"${sec.id}\" has negative offset or size`);\n      }\n      if (sec.offset + sec.size > totalSize - SHA256_SIZE) {\n        throw new Error(\n          `Section \"${sec.id}\" extends beyond buffer ` +\n            `(offset=${sec.offset}, size=${sec.size}, bufLen=${totalSize})`,\n        );\n      }\n    }\n\n    // Check for overlapping sections","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/rvfa-format.ts#L332-L368","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Regenerate the appliance with RvfaBuilder.build() which emits a schema-conformant header.","If interoperating with a custom producer, diff its header object against validateHeader's checks in rvfa-format.ts.","Inspect the parsed header fields (dump the JSON) to find which required field is missing or mistyped.","Do not patch the header by hand unless you also fix the section offsets and footer SHA256."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":"import { validateHeader, type RvfaHeader } from './rvfa-format.js';\n// validateHeader is exported and is a type guard:\n// function validateHeader(header: unknown): header is RvfaHeader;\n\nfunction parseHeaderSafe(buf: Buffer): RvfaHeader | null {\n  const hLen = buf.readUInt32LE(8);\n  const parsed = JSON.parse(buf.subarray(12, 12 + hLen).toString('utf-8'));\n  return validateHeader(parsed) ? parsed : null;\n}","tryCatchPattern":"try {\n  const reader = RvfaReader.fromBuffer(buf);\n} catch (e) {\n  if (/RVFA header failed validation/.test((e as Error).message)) {\n    const hLen = buf.readUInt32LE(8);\n    console.error('Header object:', JSON.parse(buf.subarray(12, 12 + hLen).toString('utf-8')));\n    throw new Error('Header is missing required fields or has wrong types; see validateHeader contract');\n  }\n  throw e;\n}","preventionTips":["Use the exported validateHeader() type-guard to pre-check any header object before parsing.","Regenerate appliances with RvfaBuilder.build() which emits a conformant header.","When interoperating with custom producers, diff against validateHeader's checks.","Keep the RvfaHeader interface and validateHeader in lockstep when evolving the schema."],"tags":["rvfa","header","schema","validation"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}