ruvnet/ruflo · error

Buffer too small to contain RVFA preamble

Error message

Buffer too small to contain RVFA preamble

What it means

RvfaReader.fromBuffer requires at least the 12-byte preamble (4 magic + 4 version + 4 header-length) before reading any field. This fires when the buffer is shorter than 12 bytes — an empty or near-empty image: a failed download saved as 0 bytes, an empty file, or a wrong path. No format field has even been read yet.

Solutions

1. Check buf.length >= 12 before calling fromBuffer
2. Verify the download: expected byte size and non-empty response body, not just HTTP 200
3. Re-download the .rvf appliance image from its gateway CID

Example fix

// before
const reader = RvfaReader.fromBuffer(await readFile(imgPath)); // 0-byte file → throws

// after
const buf = await readFile(imgPath);
if (buf.length < 12) throw new Error(`${imgPath} is ${buf.length}B — download failed, refetch`);
const reader = RvfaReader.fromBuffer(buf);

const buf = await readFile(imagePath);
if (buf.length < 12) {
  throw new Error('Appliance image empty or truncated — re-download from its CID');
}
const reader = RvfaReader.fromBuffer(buf);

function isRvfaCandidate(buf: Buffer): boolean {
  return buf.length >= 12 && buf.subarray(0, 4).toString('ascii') === 'RVFA';
}

When it happens

Trigger: `RvfaReader.fromBuffer(buf)` with an empty Buffer from readFile of an empty file (or a caught ENOENT defaulted to empty); a few-byte stub from an interrupted appliance fetch.

Common situations: An HTTP error body of length 0 written to disk as the .rvf image; sync tools that create the file before content arrives; tests passing placeholder buffers.

Related errors

• Header JSON exceeds maximum size
• Invalid RVFA magic: expected "RVFA", got
• Unsupported RVFA version
• Buffer too small for RVFP preamble
• Buffer too small to contain declared header

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

Appendix: 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 fa13ee4ad6)