{"record":{"id":"056f9c95766bcdd2","repo":"ruvnet/ruflo","slug":"failed-to-parse-rvfa-header-json","errorCode":null,"errorMessage":"Failed to parse RVFA header JSON","messagePattern":"Failed to parse RVFA header JSON","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/rvfa-format.ts","lineNumber":346,"sourceCode":"\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');\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        );","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/rvfa-format.ts#L328-L364","documentation":"Thrown by RvfaReader.fromBuffer() when JSON.parse fails on the header slice (the bytes between PREAMBLE_SIZE and PREAMBLE_SIZE + headerLen). The framing checks (size, magic, version, header-length sanity) all passed, but the bytes declared as the header are not valid UTF-8 JSON. The original parse error is swallowed and replaced by this generic message.","triggerScenarios":"Corruption of the header JSON bytes (bit-rot, partial overwrite), non-UTF-8 content in the header region, or a header-length field that points at the wrong slice (off-by-one in a custom writer).","commonSituations":"Disk corruption; a file spliced together incorrectly; a writer bug that mis-computed headerLen; an appliance that was edited in place with a hex editor.","solutions":["Regenerate the appliance from a known-good build.","If debugging a custom writer, verify headerLen equals the exact UTF-8 byte length of the JSON.","Dump the header slice (buf.subarray(12, 12+headerLen)) and inspect for non-UTF-8 or truncated JSON.","Treat the file as untrusted/corrupted and re-acquire it."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const reader = RvfaReader.fromBuffer(buf);\n} catch (e) {\n  if (/Failed to parse RVFA header JSON/.test((e as Error).message)) {\n    const hLen = buf.readUInt32LE(8);\n    console.error('Header slice:', buf.subarray(12, 12 + hLen).toString('utf-8'));\n    throw new Error('Header bytes are not valid JSON; the appliance is corrupt');\n  }\n  throw e;\n}","preventionTips":["Only use appliances produced by RvfaWriter.build() to guarantee valid header JSON.","If writing a custom producer, ensure headerLen equals the exact UTF-8 byte length of the serialized JSON.","Do not edit appliances in place with a hex editor.","Re-acquire appliances from a known-good source when the header is unparseable."],"tags":["rvfa","header","json","corruption"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}