{"record":{"id":"62db3102a6105919","repo":"ruvnet/ruflo","slug":"unknown-gguf-value-type-valuetype","errorCode":null,"errorMessage":"Unknown GGUF value type: ${valueType}","messagePattern":"Unknown GGUF value type: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":142,"sourceCode":"  }\n}\n\n/** Read a single GGUF typed value (scalar or array) from the buffer. */\nfunction readGgufValue(reader: BufferReader): unknown {\n  const valueType = reader.readU32();\n  if (valueType === GgufValueType.ARRAY) {\n    const elemType = reader.readU32();\n    const len = reader.readU64AsNumber();\n    const arr: unknown[] = [];\n    for (let i = 0; i < len; i++) {\n      const v = readScalar(reader, elemType);\n      if (v === undefined) throw new Error(`Unknown GGUF array element type: ${elemType}`);\n      arr.push(v);\n    }\n    return arr;\n  }\n  const v = readScalar(reader, valueType);\n  if (v === undefined) throw new Error(`Unknown GGUF value type: ${valueType}`);\n  return v;\n}\n\n// ── GGUF Header Parsing ─────────────────────────────────────\n\n/**\n * Parse the header and metadata from a GGUF file without loading tensors.\n * Reads only the first 256 KB of the file.\n */\nexport 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 {","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L124-L160","documentation":"Thrown by readGgufValue when reading a non-array scalar whose valueType is not handled by readScalar (returns undefined). Unlike the array case, this is for top-level metadata values: the type code read as the first u32 of the value is not in the supported GgufValueType set. Indicates an unsupported GGUF value type or buffer misalignment.","triggerScenarios":"Reading a GGUF metadata KV pair whose value type is outside the implemented set, or the buffer is misaligned (e.g. an earlier value was misread, shifting all subsequent reads) so the u32 consumed as a type code is garbage.","commonSituations":"GGUF spec revision adding new scalar types not yet supported; corrupt/partial download causing byte misalignment; reading a file that is not actually GGUF after the header. Note the per-KV try/catch in parseGgufBuffer may swallow this, leaving the key absent from metadata rather than failing the whole parse.","solutions":["If only a few keys fail, the parse tolerates it (per-entry try/catch) — check whether the missing metadata matters for your use case.","Validate the file with llama.cpp to confirm whether the type is genuinely unsupported or the file is corrupt.","Re-download to rule out truncation/corruption.","If a legitimate new type is needed, add it to GgufValueType and readScalar, then ensure the buffer reader can decode its width."],"exampleFix":"// before\n// readScalar returns undefined for valueType\n\n// after\n// add the missing type to the value-type enum and reader:\nenum GgufValueType { /* ... */ NEW_TYPE = 9 }\nfunction readScalar(reader: BufferReader, t: number): unknown {\n  switch (t) {\n    // ...\n    case GgufValueType.NEW_TYPE: return reader.readU32();\n  }\n}","handlingStrategy":"fallback","validationCode":"// Cannot pre-check without reading; rely on the per-KV try/catch in parseGgufBuffer\n// which already tolerates unknown scalar types by skipping the key.","typeGuard":"function isKnownValueType(t: number): boolean {\n  return Object.values(GgufValueType).includes(t as GgufValueType);\n}","tryCatchPattern":"try {\n  return await parseGgufHeader(path);\n} catch (e) {\n  if (e instanceof Error && /Unknown GGUF value type/.test(e.message)) {\n    logger.warn({ path }, 'unsupported scalar type; metadata may be incomplete');\n  }\n  throw e;\n}","preventionTips":["Prefer GGUF v2/v3 files from reputable converters.","Add new types to GgufValueType and readScalar as the spec evolves.","Confirm buffer alignment by validating earlier values parsed correctly.","Re-download when corruption is suspected."],"tags":["gguf","binary-parsing","file-format","appliance"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}