ruvnet/ruflo · error

Header length extends beyond buffer

Error message

Header length extends beyond buffer

What it means

In the signing parser, headerLen (read as u32LE at offset 8) plus the 12-byte preamble extends past buf.length - 32, i.e. the declared header would overlap or exceed the region reserved for section data plus the 32-byte footer. Equivalent to RvfaReader's 'Buffer too small' check but reached via the signing path, which skips magic/version validation of the header body itself.

Solutions

1. Verify file integrity first: size at both ends, then footer SHA256 — truncation or length corruption will also break verification anyway
2. Ensure signing runs after the file write completes (await + fsync), not concurrently with the builder
3. If the length field is corrupt, the image is unrecoverable — rebuild it
4. Compare the value at offset 8 against file size: it must satisfy 12 + headerLen <= length - 32

Example fix

// before — sign while the builder may still be flushing
const sig = await signer.signFile(await readFile(path));

// after — serialize build and sign
await builder.buildAndWrite(path); // internally: writeFile + fh.sync()
const sig = await signer.signFile(await readFile(path));

const headerLen = buf.readUInt32LE(8);
if (12 + headerLen > buf.length - 32) throw new Error('header would overrun file — truncated');

try { await verifyFile(buf, pub); }
catch (e) {
  if (/Header length extends beyond buffer/.test(String((e as Error).message))) {
    // re-fetch/rebuild; length field or file size is wrong
  }
  throw e;
}

When it happens

Trigger: Any signing/verification API built on parseRvfaBinary receiving a file where readUInt32LE(8) is inflated or the file is truncated after the preamble: partially transferred images, or a corrupted length field from bit rot or bad tooling.

Common situations: Same family as the reader-side error: interrupted transfers and truncated writes; additionally, signing pipelines that run over a file still being written concurrently (read a half-flushed preamble with a stale length).

Related errors

• Buffer too small to be a valid RVFA file
• Buffer too small to contain declared header
• Section " " extends beyond buffer (offset= , size= …
• Failed to parse RVFA header JSON
• Footer hash must be bytes, got

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

Appendix: source

Thrown at v3/@claude-flow/cli/src/appliance/rvfa-signing.ts:183

  headerEnd: number;
  sectionData: Buffer;
  footer: Buffer;
} {
  if (buf.length < PREAMBLE_SIZE + SHA256_SIZE) {
    throw new Error('Buffer too small to be a valid RVFA file');
  }

  const magic = buf.subarray(0, 4).toString('ascii');
  if (magic !== 'RVFA') {
    throw new Error(`Invalid RVFA magic: expected "RVFA", got "${magic}"`);
  }

  const headerLen = buf.readUInt32LE(8);
  const headerStart = PREAMBLE_SIZE;
  const headerEnd = headerStart + headerLen;

  if (headerEnd > buf.length - SHA256_SIZE) {
    throw new Error('Header length extends beyond buffer');
  }

  const headerJson = buf.subarray(headerStart, headerEnd).toString('utf-8');
  let header: Record<string, unknown>;
  try {
    header = JSON.parse(headerJson) as Record<string, unknown>;
  } catch {
    throw new Error('Failed to parse RVFA header JSON');
  }

  const footer = buf.subarray(buf.length - SHA256_SIZE);
  const sectionData = buf.subarray(headerEnd, buf.length - SHA256_SIZE);

  return { header, headerStart, headerEnd, sectionData, footer };
}

/**
 * Compute the signing digest for an RVFA file.

View on GitHub (pinned to fa13ee4ad6)