What causes "Section "${sec.id}" has negative offset or size" in ruvnet/ruflo?

Regenerate the appliance; offsets and sizes must be non-negative.

ruvnet/ruflo · error · Error

Section "${sec.id}" has negative offset or size

Error message

Section "${sec.id}" has negative offset or size

What it means

Thrown by RvfaReader.fromBuffer() during section bounds-checking when a section's offset or size is negative. Sections are described in the parsed header; a negative offset or size is always invalid (the buffer is addressed by unsigned subarray, so a negative value indicates corruption of the header JSON, not a legitimate small section).

Source

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

    // 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;
    for (const sec of header.sections) {
      if (sec.offset < 0 || sec.size < 0) {
        throw new Error(`Section "${sec.id}" has negative offset or size`);
      }
      if (sec.offset + sec.size > totalSize - SHA256_SIZE) {
        throw new Error(
          `Section "${sec.id}" extends beyond buffer ` +
            `(offset=${sec.offset}, size=${sec.size}, bufLen=${totalSize})`,
        );
      }
    }

    // Check for overlapping sections
    const sorted = [...header.sections].sort((a, b) => a.offset - b.offset);
    for (let i = 1; i < sorted.length; i++) {
      const prev = sorted[i - 1];
      const curr = sorted[i];
      if (prev.offset + prev.size > curr.offset) {
        throw new Error(
          `Sections "${prev.id}" and "${curr.id}" overlap ` +
            `(${prev.offset}+${prev.size} > ${curr.offset})`,

View on GitHub (pinned to 6b01dc5a68)

Solutions

Regenerate the appliance; offsets and sizes must be non-negative.
If writing a custom producer, ensure every section's offset and size are set to actual non-negative values before serializing.
Inspect the header JSON to find which section has the negative value.
Do not simply clamp negatives to zero — investigate the producer bug.

Defensive patterns

Strategy: validation

Validate before calling

import { validateHeader } from './rvfa-format.js';
function sectionsHaveNonNegativeBounds(buf: Buffer): boolean {
  const hLen = buf.readUInt32LE(8);
  const parsed = JSON.parse(buf.subarray(12, 12 + hLen).toString('utf-8'));
  if (!validateHeader(parsed)) return false;
  return (parsed as any).sections.every((s: any) => s.offset >= 0 && s.size >= 0);
}

Try / catch

try {
  const reader = RvfaReader.fromBuffer(buf);
} catch (e) {
  if (/negative offset or size/.test((e as Error).message)) {
    throw new Error('Section table contains negative offset/size; header is corrupt or hand-edited');
  }
  throw e;
}

Prevention

Always populate section offset and size with real non-negative values before serializing.
Use RvfaWriter.build() which resolves offsets iteratively and never leaves negatives.
Never use -1 as a sentinel in section metadata.
Inspect the section table when this fires to find the offending entry.

When it happens

Trigger: A header where one or more RvfaSection entries have offset<0 or size<0. This can only happen if the header JSON was hand-edited, corrupted, or produced by a buggy writer that left placeholder/zero-then-decrement values.

Common situations: A test fixture with placeholder offsets (-1) that were never resolved; bit-rot flipping a sign bit in a numeric field; a third-party writer that used -1 as a sentinel for 'empty'.

Related errors

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