ruvnet/ruflo · error · Error

Section "${id}" exceeds buffer bounds

Error message

Section "${id}" exceeds buffer bounds

What it means

Thrown when a section's declared offset+size would read past the end of the buffer minus the trailing SHA256 footer. The header's geometry disagrees with the actual bytes, indicating a corrupt, truncated, or tampered image.

Source

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

  /** List all sections declared in the header. */
  getSections(): RvfaSection[] {
    return this.header.sections;
  }

  /**
   * Extract and decompress a section by its id.
   *
   * @param id  The section identifier (e.g. 'kernel', 'runtime').
   * @returns   The decompressed section payload.
   */
  extractSection(id: string): Buffer {
    const sec = this.header.sections.find((s) => s.id === id);
    if (!sec) {
      throw new Error(`Section "${id}" not found`);
    }

    if (sec.offset + sec.size > this.buf.length - SHA256_SIZE) {
      throw new Error(`Section "${id}" exceeds buffer bounds`);
    }

    const raw = this.buf.subarray(sec.offset, sec.offset + sec.size);

    if (sec.compression === 'gzip') {
      return gunzipSync(raw);
    }
    if (sec.compression === 'zstd') {
      // zstd not natively supported — attempt gzip fallback (mirrors writer)
      try {
        return gunzipSync(raw);
      } catch {
        throw new Error(
          'zstd decompression is not supported in this environment',
        );
      }
    }

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Re-acquire the RVFA file (re-download or rebuild) and retry.
2. Run the reader's integrity/verify routine before extracting sections.
3. Confirm writer and reader are the same RVFA format version.

const SHA256_SIZE = 32;
function sectionFits(buf: Buffer, sec: { offset: number; size: number }): boolean {
  return sec.offset + sec.size <= buf.length - SHA256_SIZE;
}
const sec = reader.getSections().find(s => s.id === id);
if (sec && !sectionFits(buf, sec)) {
  throw new Error('RVFA file appears truncated; re-acquire it');
}

try {
  return reader.extractSection(id);
} catch (e) {
  if (e instanceof Error && /exceeds buffer bounds/.test(e.message)) {
    // re-download / rebuild the image, then retry once with fresh bytes
  }
  throw e;
}

When it happens

Trigger: Extracting a section from an RVFA whose header declares offset/size beyond the buffer: interrupted download, partial write, a hand-edited header, or a writer/reader version skew producing inconsistent offsets.

Common situations: Download cut short; file truncated by a size-limited channel; mismatched writer and reader versions; bit-flip in offset/size fields.

Related errors

• Sections "${prev.id}" and "${curr.id}" overlap (${prev.offse
• Header length extends beyond buffer
• KV cache file too small
• Invalid KV cache magic: 0x${magic.toString(16)}
• KV cache file truncated

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