ruvnet/ruflo · error · Error

Unknown GGUF value type: ${valueType}

Error message

Unknown GGUF value type: ${valueType}

What it means

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.

Source

Thrown at v3/@claude-flow/cli/src/appliance/gguf-engine.ts:142

  }
}

/** Read a single GGUF typed value (scalar or array) from the buffer. */
function readGgufValue(reader: BufferReader): unknown {
  const valueType = reader.readU32();
  if (valueType === GgufValueType.ARRAY) {
    const elemType = reader.readU32();
    const len = reader.readU64AsNumber();
    const arr: unknown[] = [];
    for (let i = 0; i < len; i++) {
      const v = readScalar(reader, elemType);
      if (v === undefined) throw new Error(`Unknown GGUF array element type: ${elemType}`);
      arr.push(v);
    }
    return arr;
  }
  const v = readScalar(reader, valueType);
  if (v === undefined) throw new Error(`Unknown GGUF value type: ${valueType}`);
  return v;
}

// ── GGUF Header Parsing ─────────────────────────────────────

/**
 * Parse the header and metadata from a GGUF file without loading tensors.
 * Reads only the first 256 KB of the file.
 */
export async function parseGgufHeader(path: string): Promise<GgufMetadata> {
  const fileInfo = await fsStat(path);
  const readSize = Math.min(fileInfo.size, 256 * 1024);
  const fh = await open(path, 'r');
  try {
    const buf = Buffer.alloc(readSize);
    await fh.read(buf, 0, readSize, 0);
    return parseGgufBuffer(buf, fileInfo.size, path);
  } finally {

View on GitHub (pinned to 6b01dc5a68)

Solutions

  1. If only a few keys fail, the parse tolerates it (per-entry try/catch) — check whether the missing metadata matters for your use case.
  2. Validate the file with llama.cpp to confirm whether the type is genuinely unsupported or the file is corrupt.
  3. Re-download to rule out truncation/corruption.
  4. If a legitimate new type is needed, add it to GgufValueType and readScalar, then ensure the buffer reader can decode its width.

Example fix

// before
// readScalar returns undefined for valueType

// after
// add the missing type to the value-type enum and reader:
enum GgufValueType { /* ... */ NEW_TYPE = 9 }
function readScalar(reader: BufferReader, t: number): unknown {
  switch (t) {
    // ...
    case GgufValueType.NEW_TYPE: return reader.readU32();
  }
}
Defensive patterns

Strategy: fallback

Validate before calling

// Cannot pre-check without reading; rely on the per-KV try/catch in parseGgufBuffer
// which already tolerates unknown scalar types by skipping the key.

Type guard

function isKnownValueType(t: number): boolean {
  return Object.values(GgufValueType).includes(t as GgufValueType);
}

Try / catch

try {
  return await parseGgufHeader(path);
} catch (e) {
  if (e instanceof Error && /Unknown GGUF value type/.test(e.message)) {
    logger.warn({ path }, 'unsupported scalar type; metadata may be incomplete');
  }
  throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/62db3102a6105919. Report an issue: GitHub.