ruvnet/ruflo · error · Error

zstd decompression is not supported in this environment

Error message

zstd decompression is not supported in this environment

What it means

Thrown when a section declares zstd compression and the library's gzip fallback on those bytes also fails. The reader has no native zstd decoder, so zstd-compressed sections cannot be extracted in this environment.

Source

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

    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',
        );
      }
    }

    // compression === 'none'
    return Buffer.from(raw);
  }

  /**
   * Verify the integrity of the RVFA image.
   *
   * Checks:
   *  1. Magic bytes
   *  2. Version number
   *  3. SHA256 of each section's compressed data
   *  4. SHA256 footer (all section data combined)
   */

View on GitHub (pinned to 6b01dc5a68)

Solutions

Repackage the RVFA with 'gzip' or 'none' compression.
Run extraction on Node 22+ (zlib exposes zstdUncompress) and patch the reader to use it.
Standardize team-wide on a compression every consumer supports.

Example fix

// before (writer)
sections.push({ id: 'kernel', compression: 'zstd', offset, size });

// after
sections.push({ id: 'kernel', compression: 'gzip', offset, size });

Defensive patterns

Strategy: fallback

Validate before calling

const zstdSections = reader.getSections().filter(s => s.compression === 'zstd');
const hasZstd = typeof (require('zlib').zstdUncompress) === 'function';
if (zstdSections.length > 0 && !hasZstd) {
  throw new Error('RVFA contains zstd sections; rebuild with gzip or run on Node 22+');
}

Try / catch

try {
  return reader.extractSection(id);
} catch (e) {
  if (e instanceof Error && /zstd decompression is not supported/.test(e.message)) {
    // switch to a gzip- or none-compressed image variant
  }
  throw e;
}

Prevention

Standardize portable RVFA images on gzip.
Detect zstd sections at validate time, not at extract time.
Pin producer and consumer Node versions when zstd is required.

When it happens

Trigger: Extracting a section whose header.compression === 'zstd' on a runtime without a zstd-capable zlib, where the best-effort gunzipSync on the zstd payload throws.

Common situations: RVFA written by a toolchain that defaults to zstd; older Node without zlib.zstdUncompress; cross-environment image built on a zstd-capable host but extracted elsewhere.

Related errors

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