{"record":{"id":"6d1de217d6292f90","repo":"ruvnet/ruflo","slug":"invalid-gguf-magic-0x-magic-tostring-16-expec","errorCode":null,"errorMessage":"Invalid GGUF magic: 0x${magic.toString(16)} (expected 0x46554747)","messagePattern":"Invalid GGUF magic: 0x(.+?) \\(expected 0x46554747\\)","errorType":"exception","errorClass":null,"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/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L152-L188","documentation":"parseGgufBuffer reads the first 4 bytes and requires the little-endian magic 0x46554747 (ASCII 'GGUF'); anything else throws immediately. The bytes at the given path are simply not a GGUF model — wrong file, a text/JSON document, an HTML error page saved with a .gguf extension, or a corrupted download.","triggerScenarios":"parseGgufHeader or model loading pointed at a non-GGUF path; a git-lfs pointer file or S3 error XML downloaded as the 'model'; passing a .safetensors/.bin file; a truncated-to-zero file.","commonSituations":"Config or CLI flag referencing the wrong path; download helpers that silently save error responses; case-mismatched filenames on case-sensitive filesystems.","solutions":["Confirm the path: a real GGUF starts with the ASCII bytes 'GGUF' (hex 47 47 55 46)","Re-download the model from a trusted source and verify size/checksum","Fix the model path/config to point at the .gguf artifact, not a pointer or metadata file"],"exampleFix":"// before\nconst meta = await parseGgufHeader(cfg.modelPath);\n\n// after\nconst fd = await open(cfg.modelPath);\nconst head = Buffer.alloc(4);\nawait fd.read(head, 0, 4, 0); await fd.close();\nif (head.toString('ascii') !== 'GGUF') throw new Error('not a GGUF file');\nconst meta = await parseGgufHeader(cfg.modelPath);","handlingStrategy":"validation","validationCode":"const fh = await open(path, 'r');\nconst head = Buffer.alloc(4);\nawait fh.read(head, 0, 4, 0); await fh.close();\nif (head.toString('ascii') !== 'GGUF') throw new Error('not a GGUF model');\nconst meta = await parseGgufHeader(path);","typeGuard":"async function looksLikeGguf(path: string): Promise<boolean> {\n  const fh = await open(path, 'r');\n  const b = Buffer.alloc(4);\n  const { bytesRead } = await fh.read(b, 0, 4, 0);\n  await fh.close();\n  return bytesRead === 4 && b.toString('ascii') === 'GGUF';\n}","tryCatchPattern":"try { meta = await parseGgufHeader(path); }\ncatch (e) { if (e instanceof Error && e.message.includes('Invalid GGUF magic')) { rejectModel(path); } else throw e; }","preventionTips":["Check the first 4 bytes before any GGUF parse","Verify model downloads by size/checksum so error pages never reach the parser","Give cache and model files distinct extensions to prevent path mix-ups"],"tags":["gguf","file-format","magic-bytes","nodejs"],"backgroundTag":"invalid-file-magic","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"}