{"record":{"id":"81d31802a03f1006","repo":"janhq/jan","slug":"invalid-gguf-file-s-error-message-file-for","errorCode":null,"errorMessage":"Invalid GGUF file(s): ${error.message || 'File format validation failed'}","messagePattern":"Invalid GGUF file\\(s\\): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"extensions/llamacpp-extension/src/index.ts","lineNumber":2092,"sourceCode":"        // Only asked for a DFlash-architecture draft, since that is the one\n        // case a tensor decides (DSpark = DFlash + Markov head).\n        const hasMarkovHead =\n          draftMetadata.metadata?.['general.architecture'] === 'dflash'\n            ? (await findGgufTensors(fullDraftPath, [MARKOV_HEAD_TENSOR]))\n                .length > 0\n            : undefined\n        specKind = resolveSpecDraftKind(draftMetadata.metadata, {\n          hasMarkovHead,\n          hint: opts.specDraftKind,\n        })\n        const draftLayers = detectMtpLayersFromGgufMeta(draftMetadata.metadata)\n        // Only an MTP head reports nextn layers; the other flavours have none,\n        // and the count is what makes the settings panel offer the toggle.\n        mtpLayers = draftLayers > 0 ? draftLayers : Math.max(mtpLayers, 1)\n      }\n    } catch (error) {\n      logger.error('GGUF validation failed:', error)\n      throw new Error(\n        `Invalid GGUF file(s): ${\n          error.message || 'File format validation failed'\n        }`\n      )\n    }\n\n    // Calculate file sizes\n    let size_bytes = (await fs.fileStat(fullModelPath)).size\n    if (mmprojPath) {\n      size_bytes += (\n        await fs.fileStat(await joinPath([janDataFolderPath, mmprojPath]))\n      ).size\n    }\n    if (draftModelPath) {\n      size_bytes += (\n        await fs.fileStat(await joinPath([janDataFolderPath, draftModelPath]))\n      ).size\n    }","sourceCodeStart":2074,"sourceCodeEnd":2110,"githubUrl":"https://github.com/janhq/jan/blob/7205d770c1e097c3daf35a911176410e93bc5564/extensions/llamacpp-extension/src/index.ts#L2074-L2110","documentation":"During load, the extension validates the GGUF file(s) (including reading metadata such as nextn/draft layer counts). Any exception from that validation is logged and rethrown as 'Invalid GGUF file(s): ...', meaning the file is corrupt, truncated, or not a GGUF at all.","triggerScenarios":"Calling loadModel with a modelPath pointing to a corrupt or truncated .gguf download, a non-GGUF file (e.g. safetensors, HTML error page saved as .gguf), or an mmproj file that fails format checks.","commonSituations":"Interrupted downloads leaving partial GGUFs; wrong file picked manually (safetensors from HuggingFace instead of GGUF); proxy/captive portal returning HTML that got saved as the model; corrupted storage.","solutions":["Delete the corrupt file and re-download the model; verify size/checksum against the source","Confirm the file is actually GGUF format (magic bytes 'GGUF'), not safetensors or an HTML error page","Re-import the model pointing at a known-good GGUF build","Check available disk space and retry the download if it was truncated"],"exampleFix":"// before\nawait loadModel({ modelPath: '/models/model.gguf' }) // truncated download\n// after\nawait downloadModel('https://.../model.gguf', { overwrite: true }) // re-fetch\nawait loadModel({ modelPath: '/models/model.gguf' })","handlingStrategy":"validation","validationCode":"const fd = await fs.openAsync(path, 'r'); const buf = Buffer.alloc(4)\nawait fd.read(buf, 0, 4, 0)\nif (buf.toString('ascii', 0, 4) !== 'GGUF') throw new Error(`not a GGUF: ${path}`)\nawait loadModel({ modelPath: path })","typeGuard":null,"tryCatchPattern":"try {\n  await loadModel(opts)\n} catch (e) {\n  if (e.message.startsWith('Invalid GGUF file(s):')) {\n    await redownloadCorruptedModel(opts.modelPath); return loadModel(opts)\n  }\n  throw e\n}","preventionTips":["Verify download completeness (size/checksum) before loading","Download GGUF, never safetensors, for this engine","Beware proxies saving HTML error pages as .gguf","Keep disk space headroom to avoid truncated writes"],"tags":["gguf","corrupt-file","validation"],"backgroundTag":"file-format-validation-failed","analyzedSha":"7205d770c1e097c3daf35a911176410e93bc5564","analyzedAt":"2026-09-17T14:27:30.100Z","contentChangedAt":"2026-09-17T14:27:30.100Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}