{"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":null,"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/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L157-L193","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reconvert/re-download the model as GGUF v2 or v3 using current llama.cpp tooling","Upgrade @claude-flow/cli — newer builds may extend the accepted version range","Check the version field with a gguf dump tool to confirm before converting"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const fh = await open(path, 'r');\nconst b = Buffer.alloc(8);\nawait fh.read(b, 0, 8, 0); await fh.close();\nif (b.toString('ascii', 0, 4) !== 'GGUF') throw new Error('not GGUF');\nconst version = b.readUInt32LE(4);\nif (version < 2 || version > 3) throw new Error(`GGUF v${version} unsupported here`);","typeGuard":"function isSupportedGgufVersion(head8: Buffer): boolean {\n  return head8.toString('ascii', 0, 4) === 'GGUF'\n    && head8.readUInt32LE(4) >= 2 && head8.readUInt32LE(4) <= 3;\n}","tryCatchPattern":"try { meta = await parseGgufHeader(path); }\ncatch (e) { if (e instanceof Error && e.message.includes('Unsupported GGUF version')) { reconvertModel(path); } else throw e; }","preventionTips":["Standardize on GGUF v2/v3 artifacts for this engine","Re-convert legacy v1 files with current llama.cpp tools before use","Re-check supported versions when upgrading model sources or the CLI"],"tags":["gguf","file-format","version-mismatch","nodejs"],"backgroundTag":"unsupported-file-version","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}