ruvnet/ruflo · error · Error

Unsupported GGUF version: ${version} (expected 2 or 3)

Error message

Unsupported GGUF version: ${version} (expected 2 or 3)

What it means

Thrown by parseGgufBuffer after the magic check when the version u32 is not 2 or 3. GGUF evolved through versions; this parser supports v2 and v3 only. A version outside that range means either a v1 (legacy GGUF/GGML) file or a future v4+ that the parser does not yet understand.

Source

Thrown at v3/@claude-flow/cli/src/appliance/gguf-engine.ts:175

    const buf = Buffer.alloc(readSize);
    await fh.read(buf, 0, readSize, 0);
    return parseGgufBuffer(buf, fileInfo.size, path);
  } finally {
    await fh.close();
  }
}

function parseGgufBuffer(buf: Buffer, fileSize: number, filePath: string): GgufMetadata {
  const reader = new BufferReader(buf);

  const magic = reader.readU32();
  if (magic !== GGUF_MAGIC) {
    throw new Error(`Invalid GGUF magic: 0x${magic.toString(16)} (expected 0x${GGUF_MAGIC.toString(16)})`);
  }

  const version = reader.readU32();
  if (version < 2 || version > 3) {
    throw new Error(`Unsupported GGUF version: ${version} (expected 2 or 3)`);
  }

  const tensorCount = reader.readU64AsNumber();
  const kvCount = reader.readU64AsNumber();

  const metadata: Record<string, unknown> = {};
  for (let i = 0; i < kvCount; i++) {
    if (reader.remaining < 12) break;
    try {
      const key = reader.readString();
      metadata[key] = readGgufValue(reader);
    } catch {
      break; // reached end of read window
    }
  }

  const arch = asString(metadata['general.architecture']);
  const pfx = arch || 'llama'; // fallback prefix for well-known keys

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Re-export or re-download the model in GGUF v2 or v3 using a current converter (e.g. latest llama.cpp's quantize/export).
2. If you must read a v1 file, use a legacy GGML/GGUF reader — this parser intentionally rejects it.
3. For a future version, upgrade the parser to support the new spec (and widen the range check) once the format is documented.
4. Corrupt-file check: confirm with a reference reader whether the version is real or garbage.

Example fix

// before
const meta = await parseGgufHeader(oldModelPath); // throws on v1

// after
// re-quantize with a current toolchain to emit v3:
//   llama-quantize --allow-requantize model.bin model.gguf Q4_K_M
const meta = await parseGgufHeader(modelV3Path);

// Read the version field and reject early with a clearer message:
async function ggufVersion(path: string): Promise<number> {
  const fh = await open(path, 'r');
  const buf = Buffer.alloc(8);
  await fh.read(buf, 0, 8, 0);
  await fh.close();
  if (buf.readUInt32LE(0) !== 0x46554747) throw new Error('not GGUF');
  return buf.readUInt32LE(4);
}

function isSupportedVersion(v: number): boolean {
  return v === 2 || v === 3;
}

try {
  return await parseGgufHeader(path);
} catch (e) {
  if (e instanceof Error && /Unsupported GGUF version/.test(e.message)) {
    throw new Error('re-export the model as GGUF v2 or v3');
  }
  throw e;
}

When it happens

Trigger: Loading a GGUF v1 file (very early format, predating current tooling), or a brand-new v4+ file produced by a newer writer than this parser supports. The check is a hard range bound: version < 2 || version > 3.

Common situations: Mixing old and new model files; a model exported by bleeding-edge tooling using a newer GGUF revision; bit-rot/corruption making the version field read as a large random number (though magic usually fails first).

Related errors

• String length ${len} exceeds remaining buffer
• Unknown GGUF array element type: ${elemType}
• Unknown GGUF value type: ${valueType}
• Invalid GGUF magic: 0x${magic.toString(16)} (expected 0x${GG
• KV cache file too small

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