{"record":{"id":"1efe0ab89fa247c6","repo":"tobi/qmd","slug":"model-file-is-not-valid-gguf-expected-magic-gguf","errorCode":null,"errorMessage":"Model file is not valid GGUF (expected magic \"GGUF\", got \"${inspection.magic ?? \"unknown\"}\", file is ${formatModelFileSize(inspection.sizeBytes ?? 0)}).\\nModel: ${modelUri}\\nPath:  ${filePath}\\n\\nThe file has been removed. Run the command again to re-download.","messagePattern":"Model file is not valid GGUF \\(expected magic \"GGUF\", got \"(.+?)\", file is (.+?)\\)\\.\\\\nModel: (.+?)\\\\nPath:  (.+?)\\\\n\\\\nThe file has been removed\\. Run the command again to re-download\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/llm.ts","lineNumber":476,"sourceCode":"  try {\n    unlinkSync(filePath);\n  } catch { /* best effort */ }\n\n  if (inspection.kind === \"html\") {\n    throw new Error(\n      `Downloaded model file is an HTML page, not a GGUF model (${formatModelFileSize(inspection.sizeBytes ?? 0)}).\\n` +\n      `Something is intercepting the download from huggingface.co (a proxy, firewall, or captive portal).\\n\\n` +\n      `Model: ${modelUri}\\n` +\n      `Path:  ${filePath}\\n\\n` +\n      `To fix this, either:\\n` +\n      `  1. Try a HuggingFace mirror:  HF_ENDPOINT=https://hf-mirror.com qmd embed\\n` +\n      `  2. Download the model manually and set the env var, e.g.:\\n` +\n      `       QMD_EMBED_MODEL=/path/to/model.gguf qmd embed\\n\\n` +\n      `Note: 'qmd search' works without any model downloads.`\n    );\n  }\n\n  throw new Error(\n    `Model file is not valid GGUF (expected magic \"GGUF\", got \"${inspection.magic ?? \"unknown\"}\", file is ${formatModelFileSize(inspection.sizeBytes ?? 0)}).\\n` +\n    `Model: ${modelUri}\\n` +\n    `Path:  ${filePath}\\n\\n` +\n    `The file has been removed. Run the command again to re-download.`\n  );\n}\n\n\n/**\n * node-llama-cpp prints a multi-line download progress bar when the second\n * argument is a directory string (`cli` defaults to true). Agent transcripts\n * capture that as thousands of tokens. Always pass an options object so the\n * bar is off unless the caller opts in (#776).\n */\nfunction resolveModelFileArgs(cacheDir: string, cli = false): { directory: string; cli: boolean } {\n  return { directory: cacheDir, cli };\n}\n","sourceCodeStart":458,"sourceCodeEnd":494,"githubUrl":"https://github.com/tobi/qmd/blob/dbfd0b4736aeaf761d1a16ca8e424f071df8feb9/src/llm.ts#L458-L494","documentation":"validateGgufFile found the downloaded file does not start with the required 'GGUF' magic bytes, so it is not a usable model file. Unlike the HTML case, this catches truncated/corrupted downloads; the file has already been deleted and re-running the command will download it again.","triggerScenarios":"A model download interrupted mid-stream (disk full, process killed, connection dropped) leaving a partial file; a mirror or cache serving corrupted content; a manual QMD_EMBED_MODEL path pointing at a non-GGUF file.","commonSituations":"Killed qmd embed mid-download; flaky networks truncating large files; HF mirror serving bad artifacts; pointing QMD_EMBED_MODEL at a .bin or partially-downloaded file.","solutions":["Simply re-run the command — the bad file is removed and will re-download","If it recurs, check disk space and network stability, or verify the mirror with HF_ENDPOINT","Download the model manually from huggingface.co and set QMD_EMBED_MODEL=/path/to/model.gguf","If using a manual path, confirm the file starts with the bytes 'GGUF' (e.g. head -c 4 file | xxd)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"function isGguf(filePath: string): boolean {\n  const fd = openSync(filePath, 'r');\n  const buf = Buffer.alloc(4);\n  readSync(fd, buf, 0, 4, 0); closeSync(fd);\n  return buf.toString('utf-8') === 'GGUF';\n}","typeGuard":null,"tryCatchPattern":"for (let attempt = 1; attempt <= 3; attempt++) {\n  try { await pullModels(); break; }\n  catch (e) {\n    if (e instanceof Error && e.message.includes('not valid GGUF') && attempt < 3) continue;\n    throw e;\n  }\n}","preventionTips":["Re-run after partial downloads — bad files are auto-removed","Verify manual model files start with GGUF magic before setting QMD_EMBED_MODEL","Ensure adequate disk space before large downloads"],"tags":["model-download","corrupt-file","gguf"],"backgroundTag":"corrupt-download-checksum","analyzedSha":"dbfd0b4736aeaf761d1a16ca8e424f071df8feb9","analyzedAt":"2026-08-28T18:07:46.628Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}