What causes "Buffer too small to contain declared header" in ruvnet/ruflo?

Re-fetch or rebuild the appliance; the header region is incomplete.

ruvnet/ruflo · error · Error

Buffer too small to contain declared header

Error message

Buffer too small to contain declared header

What it means

Thrown by RvfaReader.fromBuffer() when PREAMBLE_SIZE(12) + declared header length exceeds the actual buffer length. Unlike error 133 (which rejects oversized headers outright), this fires for a header length that is plausible (<1 MiB) but still larger than what the buffer contains — i.e. a truncated header region.

Source

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

    }

    // 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);
    if (headerLen > MAX_HEADER_JSON_SIZE) {
      throw new Error(
        `Header JSON exceeds maximum size (${headerLen} > ${MAX_HEADER_JSON_SIZE})`,
      );
    }
    if (PREAMBLE_SIZE + headerLen > buf.length) {
      throw new Error('Buffer too small to contain declared header');
    }

    // Parse header JSON
    const headerSlice = buf.subarray(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLen);
    let parsed: unknown;
    try {
      parsed = JSON.parse(headerSlice.toString('utf-8'));
    } catch {
      throw new Error('Failed to parse RVFA header JSON');
    }

    if (!validateHeader(parsed)) {
      throw new Error('RVFA header failed validation');
    }
    const header = parsed as RvfaHeader;

    // Bounds-check every section offset
    const totalSize = buf.length;

View on GitHub (pinned to 6b01dc5a68)

Solutions

Re-fetch or rebuild the appliance; the header region is incomplete.
Compare file size against the producer's reported size.
If you control the producer, emit a sidecar size manifest for round-trip validation.
Reject files whose preamble-length plus header exceeds remaining bytes before parsing.

Defensive patterns

Strategy: validation

Validate before calling

const RVFA_PRE = 12;
function headerFitsInBuffer(buf: Buffer): boolean {
  if (buf.length < RVFA_PRE) return false;
  const hLen = buf.readUInt32LE(8);
  return hLen <= 1024 * 1024 && RVFA_PRE + hLen <= buf.length;
}

Try / catch

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/Buffer too small to contain declared header/.test((e as Error).message)) {
    throw new Error('RVFA header region is truncated; re-download or rebuild the appliance');
  }
  throw e;
}

Prevention

Compare the downloaded file size against the producer's manifest.
Use content-addressed storage so truncation is detectable via CID mismatch.
Write appliances atomically (tmp + rename) to avoid partial files.
Run reader.verify() on received appliances before use.

When it happens

Trigger: The appliance file was truncated mid-header (e.g. interrupted write or download), or the header-length field is correct but the body is missing bytes. Magic and version already passed; the length is under 1 MiB.

Common situations: A killed build process left a partial .rvfa; IPFS fetch was cut short; a copy operation hit disk-full; a proxy truncated the body.

Related errors

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