ruvnet/ruflo · error

Unsupported GGUF version

Error message

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

What it means

After the magic, the next u32 is the GGUF spec version; this parser accepts only v2 and v3. v1 files from early llama.cpp (different field layout) and any future v4+ revision are rejected so the parser's layout assumptions for tensor/KV counts are not violated.

Solutions

1. Reconvert/re-download the model as GGUF v2 or v3 using current llama.cpp tooling
2. Upgrade @claude-flow/cli — newer builds may extend the accepted version range
3. Check the version field with a gguf dump tool to confirm before converting

const fh = await open(path, 'r');
const b = Buffer.alloc(8);
await fh.read(b, 0, 8, 0); await fh.close();
if (b.toString('ascii', 0, 4) !== 'GGUF') throw new Error('not GGUF');
const version = b.readUInt32LE(4);
if (version < 2 || version > 3) throw new Error(`GGUF v${version} unsupported here`);

function isSupportedGgufVersion(head8: Buffer): boolean {
  return head8.toString('ascii', 0, 4) === 'GGUF'
    && head8.readUInt32LE(4) >= 2 && head8.readUInt32LE(4) <= 3;
}

try { meta = await parseGgufHeader(path); }
catch (e) { if (e instanceof Error && e.message.includes('Unsupported GGUF version')) { reconvertModel(path); } else throw e; }

When it happens

Trigger: Loading a GGUF v1 file produced by pre-2023 conversion tools; loading a v4+ file written by a newer llama.cpp than this engine supports.

Common situations: Old model hoards migrated between machines; bleeding-edge converters outpacing the bundled parser; version mismatch between the tool that produced the model and @claude-flow/cli.

Related errors

• Invalid GGUF magic: 0x
• String length exceeds remaining buffer
• Unknown GGUF array element type
• Unknown GGUF value type
• Unsupported KV cache version

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

Appendix: 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 fa13ee4ad6)