{"record":{"id":"8836fefc1b7f647a","repo":"ruvnet/ruflo","slug":"invalid-gguf-magic-0x-magic-tostring-16-expec","errorCode":null,"errorMessage":"Invalid GGUF magic: 0x${magic.toString(16)} (expected 0x${GGUF_MAGIC.toString(16)})","messagePattern":"Invalid GGUF magic: 0x(.+?) \\(expected 0x(.+?)\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":170,"sourceCode":"export async function parseGgufHeader(path: string): Promise<GgufMetadata> {\n  const fileInfo = await fsStat(path);\n  const readSize = Math.min(fileInfo.size, 256 * 1024);\n  const fh = await open(path, 'r');\n  try {\n    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","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L152-L188","documentation":"Thrown by parseGgufBuffer when the first u32 of the file is not GGUF_MAGIC. The magic number is the format's identity check; a mismatch means the file is not GGUF (or is a different endianness / a different format that happens to be passed in). This is the earliest possible parse failure and runs before version/tensor/KV reads.","triggerScenarios":"Calling parseGgufHeader (or otherwise parsing) on a file that is not GGUF: a safetensors/GGML/bin file, a text file, or a renamed download. Also fires if the file is empty or only a few bytes long so the u32 read yields zeros.","commonSituations":"Wrong file selected in a model picker (e.g. a tokenizer or config JSON named .gguf), a download that produced an HTML error page saved with the .gguf extension, or endianness confusion. The message helpfully prints both the found and expected magic in hex.","solutions":["Confirm the path points to an actual GGUF file (check the file command / first bytes; GGUF magic is 'GGUF' = 0x46554747).","Re-download from the source if the file looks like an HTML error page or is suspiciously small.","Gate parseGgufHeader with a quick magic-byte check so you can give a clearer error or skip non-GGUF files in a directory scan.","Verify the file was not truncated to zero bytes by a failed transfer."],"exampleFix":"// before\nconst meta = await parseGgufHeader(candidatePath);\n\n// after\nasync function isGguf(path: string): Promise<boolean> {\n  const fh = await open(path, 'r');\n  const head = Buffer.alloc(4);\n  await fh.read(head, 0, 4, 0);\n  await fh.close();\n  return head.readUInt32LE(0) === 0x46554747;\n}\nif (!(await isGguf(candidatePath))) throw new Error('not a GGUF file; refusing to parse');","handlingStrategy":"validation","validationCode":"import { open } from 'node:fs/promises';\nasync function isGgufFile(path: string): Promise<boolean> {\n  const fh = await open(path, 'r');\n  const head = Buffer.alloc(4);\n  await fh.read(head, 0, 4, 0);\n  await fh.close();\n  return head.readUInt32LE(0) === 0x46554747; // 'GGUF'\n}\nif (!(await isGgufFile(path))) throw new Error('not a GGUF file');","typeGuard":"function isGgufMagic(buf: Buffer): boolean {\n  return buf.length >= 4 && buf.readUInt32LE(0) === 0x46554747;\n}","tryCatchPattern":"try {\n  return await parseGgufHeader(path);\n} catch (e) {\n  if (e instanceof Error && /Invalid GGUF magic/.test(e.message)) {\n    throw new Error(`'${path}' is not a GGUF file`);\n  }\n  throw e;\n}","preventionTips":["Filter directory scans by .gguf extension AND magic bytes.","Re-download files that look like HTML error pages saved as .gguf.","Do not feed tokenizer/config files to the GGUF parser.","Check the file is non-empty before parsing."],"tags":["gguf","binary-parsing","file-format","magic-number"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}