ruvnet/ruflo · error · Error

Buffer too small to contain RVFA preamble

Error message

Buffer too small to contain RVFA preamble

What it means

Thrown by RvfaReader.fromBuffer() when the buffer is shorter than PREAMBLE_SIZE (12 bytes: 4 magic + 4 version + 4 header-length). It is the first structural gate before any field is read, so it precedes the magic/version checks. Both fromBuffer and fromFile (which delegates to it) can surface this.

Source

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

  }
}

// ---------------------------------------------------------------------------
// RvfaReader
// ---------------------------------------------------------------------------
export class RvfaReader {
  private buf: Buffer;
  private header: RvfaHeader;

  private constructor(buf: Buffer, header: RvfaHeader) {
    this.buf = buf;
    this.header = header;
  }

  /** Parse an RVFA image from an in-memory Buffer. */
  static fromBuffer(buf: Buffer): RvfaReader {
    if (buf.length < PREAMBLE_SIZE) {
      throw new Error('Buffer too small to contain RVFA preamble');
    }

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

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Check the file/buffer size is well above 12 bytes before parsing.
2. Re-run the RVFA build (RvfaBuilder.build()) if the file is empty or truncated.
3. Re-download the appliance from IPFS if the fetch was interrupted.
4. Confirm the path points to an .rvfa appliance, not a .rvfp patch.

Example fix

// before
const reader = await RvfaReader.fromFile(path); // path may be empty

// after
const stat = await fs.stat(path);
if (stat.size < 12) throw new Error(`${path} is too small to be an RVFA image`);
const reader = await RvfaReader.fromFile(path);

const RVFA_PREAMBLE = 12;
function isRvfaSized(buf: Buffer): boolean {
  return Buffer.isBuffer(buf) && buf.length >= RVFA_PREAMBLE;
}

function isRvfaCandidate(buf: unknown): buf is Buffer {
  return Buffer.isBuffer(buf) && buf.length >= 12;
}

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/Buffer too small to contain RVFA preamble/.test((e as Error).message)) {
    throw new Error(`Buffer is ${buf.length} bytes; an RVFA image must be >= 12 bytes`);
  }
  throw e;
}

When it happens

Trigger: Passing an empty or near-empty Buffer to RvfaReader.fromBuffer(), or pointing fromFile() at an empty/truncated .rvfa file. Also: reading a non-appliance file (e.g. a patch, a log) whose size happens to be under 12 bytes.

Common situations: A zero-byte .rvfa left by a killed build; an interrupted download; stat()-ing the wrong path; passing a Buffer that was allocated but never populated.

Related errors

• Buffer too small for RVFP preamble
• Invalid RVFA magic: expected "RVFA", got "${magic}"
• Buffer too small to contain declared header
• Encrypted buffer too short: need >= ${minLen}B, got ${buf.le
• Invalid RVFP magic: "${magic}"

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/0a7e251cdbd96241. Report an issue: GitHub.