ruvnet/ruflo · error

Unknown GGUF value type

Error message

Unknown GGUF value type: ${valueType}

What it means

Same type switch as the array case, but for a top-level scalar metadata value: the u32 valueType read from the buffer is not one of GgufValueType 0-12 (ARRAY=9 is handled separately). This means the metadata uses a type the parser does not know, or the reader is misaligned due to earlier corruption, and parsing stops rather than guessing a width.

Solutions

1. Dump the metadata with a current gguf tool to identify the unknown type code
2. Upgrade @claude-flow/cli so its GgufValueType covers the file's spec revision
3. Reconvert the model with standard tooling to a v2/v3 file using known types
4. Reject the file outright on this error — subsequent reads would be misaligned

try { meta = await parseGgufHeader(path); }
catch (e) { if (e instanceof Error && e.message.includes('GGUF value type')) { reportUnsupportedModel(path); } else throw e; }

When it happens

Trigger: A metadata key whose value type code is >12 (future GGUF spec) or an invalid number; a value-type field read from the wrong offset after a preceding string/array was corrupt.

Common situations: Bleeding-edge llama.cpp files ahead of this engine's supported spec; converter bugs; random corruption that still passed magic and version checks.

Related errors

• Unknown GGUF array element type
• String length exceeds remaining buffer
• Invalid GGUF magic: 0x
• Unsupported GGUF version
• Invalid KV cache magic: 0x

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

Appendix: 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 fa13ee4ad6)