{"record":{"id":"7a5d40e10a6bab57","repo":"ruvnet/ruflo","slug":"invalid-rvfa-magic-expected-rvfa-got-magic","errorCode":null,"errorMessage":"Invalid RVFA magic: expected \"RVFA\", got \"${magic}\"","messagePattern":"Invalid RVFA magic: expected \"RVFA\", got \"(.+?)\"","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/rvfa-format.ts","lineNumber":318,"sourceCode":"export class RvfaReader {\n  private buf: Buffer;\n  private header: RvfaHeader;\n\n  private constructor(buf: Buffer, header: RvfaHeader) {\n    this.buf = buf;\n    this.header = header;\n  }\n\n  /** Parse an RVFA image from an in-memory Buffer. */\n  static fromBuffer(buf: Buffer): RvfaReader {\n    if (buf.length < PREAMBLE_SIZE) {\n      throw new Error('Buffer too small to contain RVFA preamble');\n    }\n\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) {","sourceCodeStart":300,"sourceCodeEnd":336,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/rvfa-format.ts#L300-L336","documentation":"The first 4 bytes of an RVFA image must be ASCII 'RVFA'. Anything else means the buffer is not an appliance image at all — most commonly it is an RVFP patch (magic 'RVFP'), an HTML/text error document, or an unrelated binary given a .rvf name.","triggerScenarios":"`RvfaReader.fromBuffer(buf)` on a .rvfp patch (magic 'RVFP'); a text file or gateway error page; garbage leading bytes from a corrupted transfer.","commonSituations":"Fetching an appliance CID that actually contains a patch; saving an error response body with the appliance filename; picking the wrong file out of a build directory.","solutions":["Inspect the first bytes (xxd file | head -1): 'RVFA' = appliance image, 'RVFP' = patch — route each to its own parser","Send patches to RvfaPatcher.parsePatchHeader, images to RvfaReader.fromBuffer","Re-download from the correct CID/artifact source"],"exampleFix":"// before\nconst reader = RvfaReader.fromBuffer(await readFile(patchPath)); // actually an RVFP patch\n\n// after\nconst buf = await readFile(path);\nconst kind = buf.subarray(0, 4).toString('ascii');\nif (kind === 'RVFP') throw new Error('This is a patch, not an appliance — use RvfaPatcher');\nif (kind !== 'RVFA') throw new Error(`Unknown artifact magic \"${kind}\"`);\nconst reader = RvfaReader.fromBuffer(buf);","handlingStrategy":"type-guard","validationCode":"const kind = buf.subarray(0, 4).toString('ascii');\nif (kind !== 'RVFA') {\n  throw new Error(`Not an RVFA appliance image (magic \"${kind}\")`);\n}","typeGuard":"function isRvfaImage(buf: Buffer): boolean {\n  return buf.length >= 12 && buf.subarray(0, 4).toString('ascii') === 'RVFA';\n}","tryCatchPattern":null,"preventionTips":["Dispatch on the 4-byte magic before choosing a parser — 'RVFA' images, 'RVFP' patches","Keep .rvf and .rvfp extensions distinct throughout build and distribution pipelines"],"tags":["rvfa-format","rvfa","magic-number","binary-format"],"backgroundTag":"invalid-magic-number","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"}