{"record":{"id":"967b2272288290f0","repo":"ruvnet/ruflo","slug":"unsupported-gguf-version-version-expected-2-o","errorCode":null,"errorMessage":"Unsupported GGUF version: ${version} (expected 2 or 3)","messagePattern":"Unsupported GGUF version: (.+?) \\(expected 2 or 3\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":175,"sourceCode":"    const buf = Buffer.alloc(readSize);\n    await fh.read(buf, 0, readSize, 0);\n    return parseGgufBuffer(buf, fileInfo.size, path);\n  } finally {\n    await fh.close();\n  }\n}\n\nfunction parseGgufBuffer(buf: Buffer, fileSize: number, filePath: string): GgufMetadata {\n  const reader = new BufferReader(buf);\n\n  const magic = reader.readU32();\n  if (magic !== GGUF_MAGIC) {\n    throw new Error(`Invalid GGUF magic: 0x${magic.toString(16)} (expected 0x${GGUF_MAGIC.toString(16)})`);\n  }\n\n  const version = reader.readU32();\n  if (version < 2 || version > 3) {\n    throw new Error(`Unsupported GGUF version: ${version} (expected 2 or 3)`);\n  }\n\n  const tensorCount = reader.readU64AsNumber();\n  const kvCount = reader.readU64AsNumber();\n\n  const metadata: Record<string, unknown> = {};\n  for (let i = 0; i < kvCount; i++) {\n    if (reader.remaining < 12) break;\n    try {\n      const key = reader.readString();\n      metadata[key] = readGgufValue(reader);\n    } catch {\n      break; // reached end of read window\n    }\n  }\n\n  const arch = asString(metadata['general.architecture']);\n  const pfx = arch || 'llama'; // fallback prefix for well-known keys","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L157-L193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Re-export or re-download the model in GGUF v2 or v3 using a current converter (e.g. latest llama.cpp's quantize/export).","If you must read a v1 file, use a legacy GGML/GGUF reader — this parser intentionally rejects it.","For a future version, upgrade the parser to support the new spec (and widen the range check) once the format is documented.","Corrupt-file check: confirm with a reference reader whether the version is real or garbage."],"exampleFix":"// before\nconst meta = await parseGgufHeader(oldModelPath); // throws on v1\n\n// after\n// re-quantize with a current toolchain to emit v3:\n//   llama-quantize --allow-requantize model.bin model.gguf Q4_K_M\nconst meta = await parseGgufHeader(modelV3Path);","handlingStrategy":"validation","validationCode":"// Read the version field and reject early with a clearer message:\nasync function ggufVersion(path: string): Promise<number> {\n  const fh = await open(path, 'r');\n  const buf = Buffer.alloc(8);\n  await fh.read(buf, 0, 8, 0);\n  await fh.close();\n  if (buf.readUInt32LE(0) !== 0x46554747) throw new Error('not GGUF');\n  return buf.readUInt32LE(4);\n}","typeGuard":"function isSupportedVersion(v: number): boolean {\n  return v === 2 || v === 3;\n}","tryCatchPattern":"try {\n  return await parseGgufHeader(path);\n} catch (e) {\n  if (e instanceof Error && /Unsupported GGUF version/.test(e.message)) {\n    throw new Error('re-export the model as GGUF v2 or v3');\n  }\n  throw e;\n}","preventionTips":["Re-quantize/export models with a current toolchain to emit v2/v3.","Do not attempt to load legacy GGML/GGUF v1 files with this parser.","Upgrade the parser when adopting a new GGUF version.","Validate with llama.cpp to confirm the real version."],"tags":["gguf","binary-parsing","version","file-format"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}