tobi/qmd · error · Error

Downloaded model file is an HTML page, not a GGUF model (${f

Error message

Downloaded model file is an HTML page, not a GGUF model (${formatModelFileSize(inspection.sizeBytes ?? 0)}).\nSomething is intercepting the download from huggingface.co (a proxy, firewall, or captive portal).\n\nModel: ${modelUri}\nPath:  ${filePath}\n\nTo fix this, either:\n  1. Try a HuggingFace mirror:  HF_ENDPOINT=https://hf-mirror.com qmd embed\n  2. Download the model manually and set the env var, e.g.:\n       QMD_EMBED_MODEL=/path/to/model.gguf qmd embed\n\nNote: 'qmd search' works without any model downloads.

What it means

After downloading a GGUF model from huggingface.co, validation found the file is actually an HTML page — typical of a proxy, captive portal, or firewall intercepting the download. The bad file is deleted automatically so a retry re-downloads, and the error suggests a mirror or manual download via QMD_EMBED_MODEL.

Source

Thrown at src/llm.ts:463

  }
}

/**
 * Validate that a file is actually a GGUF model, not an HTML error page
 * from a proxy, firewall, or failed download.
 * Throws a descriptive error if the file is not valid GGUF.
 */
function validateGgufFile(filePath: string, modelUri: string): void {
  const inspection = inspectGgufFile(filePath);
  if (!inspection.exists || inspection.valid) return; // let downstream handle missing files

  // Remove the bad file so the next attempt re-downloads
  try {
    unlinkSync(filePath);
  } catch { /* best effort */ }

  if (inspection.kind === "html") {
    throw new Error(
      `Downloaded model file is an HTML page, not a GGUF model (${formatModelFileSize(inspection.sizeBytes ?? 0)}).\n` +
      `Something is intercepting the download from huggingface.co (a proxy, firewall, or captive portal).\n\n` +
      `Model: ${modelUri}\n` +
      `Path:  ${filePath}\n\n` +
      `To fix this, either:\n` +
      `  1. Try a HuggingFace mirror:  HF_ENDPOINT=https://hf-mirror.com qmd embed\n` +
      `  2. Download the model manually and set the env var, e.g.:\n` +
      `       QMD_EMBED_MODEL=/path/to/model.gguf qmd embed\n\n` +
      `Note: 'qmd search' works without any model downloads.`
    );
  }

  throw new Error(
    `Model file is not valid GGUF (expected magic "GGUF", got "${inspection.magic ?? "unknown"}", file is ${formatModelFileSize(inspection.sizeBytes ?? 0)}).\n` +
    `Model: ${modelUri}\n` +
    `Path:  ${filePath}\n\n` +
    `The file has been removed. Run the command again to re-download.`
  );

View on GitHub (pinned to dbfd0b4736)

Solutions

1. Retry with a mirror: HF_ENDPOINT=https://hf-mirror.com qmd embed
2. Download the GGUF manually and point at it: QMD_EMBED_MODEL=/path/to/model.gguf qmd embed
3. Configure proxy env vars (HTTPS_PROXY) correctly or whitelist huggingface.co
4. Remember qmd search (BM25) works with no model at all

// Preflight: can we reach huggingface.co un-intercepted?
const res = await fetch('https://huggingface.co', { method: 'HEAD' });
const contentType = res.headers.get('content-type') ?? '';
const likelyIntercepted = !res.ok || contentType.includes('text/html');

try {
  await runEmbed();
} catch (e) {
  if (e instanceof Error && e.message.includes('HTML page')) {
    // retry with HF_ENDPOINT=https://hf-mirror.com or prompt for QMD_EMBED_MODEL path
  } else throw e;
}

When it happens

Trigger: Running `qmd embed` (or resolveModel/pullModels) on a network where huggingface.co responses are intercepted: corporate proxies, hotel/airport captive portals, or DNS-level blocks in some regions.

Common situations: Corporate networks with SSL inspection; China/GFW blocking huggingface.co; misconfigured HTTP_PROXY returning an error page; CI runners with restricted egress.

Related errors

• Model file is not valid GGUF (expected magic "GGUF", got "${

AI-assisted analysis of tobi/qmd@dbfd0b4736 (2026-08-28). Data as JSON: /api/errors/8b6dbafd801fbf18. Report an issue: GitHub.