← Back to Home

GGUF Metadata: Eight Fields That Read Back Wrong

ggufllama.cppmodel quantization

TL;DR: I wrote a GGUF file from scratch with gguf-py 0.19.0, read it back, and compared every field. Eight of them returned something different from what I wrote, and three of those raised no exception at all. The worst is general.alignment: write it as an ordinary metadata key and the writer still pads to 32 bytes while the reader looks for 64, so the library cannot read its own output — it fails with ValueError: cannot reshape array of size 0 into shape (3,). Every claim below is reproducible with the commands in this post. There are no affiliate links in this article.

// FLOW_01How I compared the write and read sides6 NODES01STEP_01Write a small file02STEP_02Read every field03STEP_03Compare values04STEP_04Check type and alignment05STEP_05Fix the call06STEP_06Re-verifyEND_OF_FLOW
How I compared the write and read sides · diagram drawn from this article
Python
Technologies referenced · icons from Simple Icons (CC0)

Why build a tiny GGUF file instead of downloading one

Most GGUF write-ups stop at "GGUF is the model format llama.cpp uses, and quantization makes it smaller". The moment you actually need to inspect a model file, the questions change: which fields drive loading behaviour, who guarantees a field's type and length, and at which step a wrong value explodes.

My starting point was small. I wanted to confirm the general.file_type and per-tensor dimensions of one model file. I have no GPU and did not want to pull down several gigabytes of weights, so I inverted the problem: write a file with the official Python package, then read it back. The file is a few hundred bytes, but it exercises the whole metadata layer.

The result is a comparison table with eight rows where the value that came back was not the value that went in, and no error interrupted the script.

Environment and two commands you can paste

Everything below ran on Windows 11 (10.0.26300), CPython 3.13.14, gguf 0.19.0 (uploaded to PyPI on 2026-05-06) and numpy 2.5.5. Install into an isolated directory so your main environment stays clean:

python -m pip install --target ./pylibs gguf==0.19.0 numpy
python -c "import sys; sys.path.insert(0,'./pylibs'); import gguf; print(gguf.GGUF_VERSION, gguf.GGUF_MAGIC, gguf.READER_SUPPORTED_VERSIONS)"

That second command prints 3 1179993927 [2, 3]: the version this writer emits, the magic number in decimal, and the fact that the reader only accepts versions 2 and 3.

Here is the smallest reproduction of everything this post claims. Save it as demo.py and run it:

import sys
sys.path.insert(0, "./pylibs")
import numpy as np
from gguf import GGUFWriter, GGUFReader

w = GGUFWriter("demo.gguf", "llama")
w.add_file_type(1)
w.add_uint32("demo.uint", 4294967295)
w.add_array("demo.arr", [1, 2, 3])
w.add_tensor("demo.weight", np.arange(6, dtype=np.float32).reshape(2, 3))
w.write_header_to_file()
w.write_kv_data_to_file()
w.write_tensors_to_file()
w.close()

r = GGUFReader("demo.gguf")
print([k for k in r.fields if not k.startswith("GGUF.")])
print(r.get_field("demo.uint").contents())
print(r.tensors[0].shape.tolist())
print(r.tensors[0].data.shape)

The last two lines print [3, 2] and (2, 3). Same array, two different dimension orders, no warning. That is the first of the eight.

Trap one: the write_header and write_footer methods do not exist

The first failure came from copying a tutorial:

w.write_header()
w.write_kv_data_to_file()
w.write_tensors_to_file()
w.write_footer()

On 0.19.0 the first line already fails:

AttributeError: 'GGUFWriter' object has no attribute 'write_header'

Loop over candidate names with hasattr and the picture is clear: write_header is False, write_footer is False, and the real names are write_header_to_file, write_kv_data_to_file, write_tensors_to_file, ti_data_to_file, flush, close. The order is fixed at four steps:

The reader has a matching trap: GGUFReader has no get(), only get_field() and get_tensor(). r.get("general.architecture") gives you AttributeError: 'GGUFReader' object has no attribute 'get'.

Trap two: reader.tensors is a list, not a dict

Nearly every snippet indexes it like a dictionary:

reader = GGUFReader(path)
t = reader.tensors["blk.0.attn_q.weight"]

On 0.19.0 that raises:

TypeError: list indices must be integers or slices, not str

reader.tensors is a plain list of ReaderTensor named tuples. Either index it or build a mapping first:

by_name = {t.name: t for t in reader.tensors}
t = by_name["blk.0.attn_q.weight"]

The difference is not cosmetic. The dictionary form reads like "look up by name" while the actual semantics are "look up by position". Had the type been permissive, a reordered tensor list would have shifted your values silently instead of raising.

Trap three: shape is the file's order, not numpy's

In demo.py I wrote a (2, 3) array. Reading it back gives tensors[0].shape == [3, 2] while tensors[0].data.shape == (2, 3).

Both sides of the source explain why. The writer loop packs ti.shape[n_dims - 1 - j], so numpy dimensions go into the file reversed (the ggml convention puts the innermost dimension first). The reader stores the raw dims untouched in ReaderTensor.shape and then reshapes the data with reversed(dims). So shape means "dimensions as stored in the file", and data.shape means "dimensions as numpy sees them". For logging, use the latter.

Quantized tensors add another layer. I wrote 144 packed bytes with raw_dtype set to Q4_K:

w.add_tensor("q4", np.zeros(144, dtype=np.uint8), raw_dtype=GGMLQuantizationType.Q4_K)

Reading back gives shape == [256] (element count), n_bytes == 144, and data.shape == (144,) (packed bytes). For quantized tensors the two are not "different order" — they measure different things. Sizing a buffer from shape overcounts by 256/144.

Trap four: get_field returns None for a missing key

f = r.get_field("general.quantization_version")
print(f.contents())

If the key is absent, get_field returns None and the next attribute access fails:

AttributeError: 'NoneType' object has no attribute 'contents'

At least that one crashes. The dangerous variant is truth-testing without touching the value: if r.get_field(key): is also false when the key exists but holds 0, which collapses "field missing" and "field is zero" into one branch. Separate the two: use key in r.fields for existence and .contents() for the value.

contents() returns Python scalars for scalars, str for strings, list for arrays, and [] for an empty array. Do not expect numpy types.

Trap five: add_array with an empty list never writes the key

This is the quietest one. The first statement of add_array is:

if len(val) == 0:
    return

No key, no log line, no exception. I wrote three keys — before, ghost (empty array) and after — and the file came back with two:

fields: ['general.architecture', 'before', 'after']
ghost present: False | kv_count declared: 3

The header declares three key-value pairs and you can only read two custom ones. So an optional vocabulary list or an optional adapter list that happens to be empty simply does not exist in your file, and every downstream if field in fields check falls through to the else branch.

The safety net is still there and now unreachable: _pack_val contains raise ValueError("Invalid GGUF metadata array. Empty array"), but the early return in add_array prevents that code from ever running. Two layers of defence where the first layer disables the second.

Trap six: a duplicate key logs one warning and overwrites, type included

Write add_uint32("dup", 1), then add_string("dup", "one"). The file is produced normally and reads back as:

after the type change: STRING = one

The only trace is one log line: Duplicated key name 'dup', overwriting it with new value 'one' of type STRING. Set the logger to ERROR, which is common in production, and you never see it. A field that should be a uint32 becomes a string, and any consumer that parses it as an integer gets something else entirely, or blows up somewhere unrelated.

A related issue sits on the same path: an array's element type is decided by its first element only, and Python int always maps to INT32. In the source, GGUFValueType.get_type returns INT32 for any int, with a # TODO: need help with 64-bit types in Python comment right beside it. So this line (the literal is 2 to the 40th):

w.add_array("big", [1099511627776])

fails during the write, not at the call:

struct.error: 'i' format requires -2147483648 <= number <= 2147483647

Meanwhile w.add_array("mixed", [1, 2.5]) raises ValueError: All items in a GGUF array should be of the same type. Two errors placed in two different stages, neither of them on the add_array line — easy to misread as a disk or file problem.

Trap seven: general.alignment is written as metadata but padding stays at 32

This is the only case in the whole experiment where the library writes a file it cannot read, and it is the one I would put at the top of any notes.

GGUF layout: after the tensor info table, pad with zeros up to a multiple of general.alignment, then the tensor data begins. The spec is explicit that the default is 32 and that align_offset uses this field.

So I took the spec literally and wrote the alignment as ordinary metadata:

w.add_uint32("general.alignment", 64)

The file came out at 192 bytes. Reading it back with the same library:

ValueError: cannot reshape array of size 0 into shape (3,)

The writer source explains it: self.data_alignment = GGUF_DEFAULT_ALIGNMENT (32) is fixed at construction time, and padding uses self.data_alignment, which has nothing to do with the general.alignment key-value. The writer pads to 32 (data starts at byte 160), the reader looks for data at a multiple of 64 (byte 192), finds nothing, and reshape fails.

The correct call sets both at once:

w.add_custom_alignment(64)

It validates "non-zero and a power of two", then assigns self.data_alignment and writes the key-value together. After the change: 256 bytes, alignment=64, data_offset=192, data reads back as [1. 1. 1.].

How the alignment is writtenFile sizedata_offsetReads back
Not written (default 32)160 B128yes
general.alignment=64 only192 Bwriter still pads to 32no, reshape error
add_custom_alignment(64)256 B192yes

The reader also validates the field, which is worth copying into your own checks: a non-UINT32 type raises ValueError: Bad type for general.alignment field, and a value that is not a power of two raises ValueError: Invalid alignment: must be a non-zero power of two. I set it to 0 and to 3 and hit the second message both times.

Trap eight: the two header counts are trusted without question

Besides magic and version, the header carries two uint64 values: the tensor count and the metadata KV count. The reader parses strictly by those numbers and cross-checks nothing.

I edited a valid file to declare tensor_count = 0. The reader succeeded and reported zero tensors — with 256 bytes of tensor data still sitting in the file, silently ignored. Setting kv_count = 999 produced:

IndexError: index 0 is out of bounds for axis 0 with size 0

An out-of-bounds IndexError has no textual relationship to "your KV count is wrong". Truncated files behave the same way: four truncation lengths produced four different exceptions (ValueError: not enough values to unpack, ValueError: When changing to a larger dtype..., IndexError: index 0 is out of bounds..., and cannot reshape array of size 39 into shape (8, 8)), and none of them said "incomplete file".

So integrity has to be computed by hand: file size >= data_offset + sum of tensor n_bytes, and the declared tensor count must equal the number of tensors actually parsed.

Versions, byte order and where the spec and the code disagree

The reader accepts versions 2 and 3 only. I rewrote the version field to 0, 1, 2, 3 and 4; 2 and 3 read fine and the rest all give the same message:

ValueError: Sorry, file appears to be version 1 which we cannot handle

Writing GGML as the magic raises ValueError: GGUF magic invalid — note that this is a custom lowercase message, not a struct.error, so exception-type fallbacks need to handle it separately.

Byte order is where the spec and the implementation part ways. The spec says: "At the time of writing, there is no way to determine if a model is big-endian; this may be rectified in future versions." The reader, however, applies a heuristic: if the low 16 bits of the version are zero, it treats the file as opposite-endian and flips parsing. I wrote a big-endian file with endianess=GGUFEndian.BIG; reading it back gave reader.byte_order == 'S' and correct field values.

One spec limit is not enforced anywhere: the spec says a tensor's n_dimensions is "Currently at most 4", yet the writer happily serialized a 5-D tensor with n_dimensions = 5, and the reader accepted it. "The spec forbids it" and "this library rejects it" are two different statements; a missing error is not proof of compliance.

Troubleshooting: four real errors and their fixes

All four were reproduced in this environment; the messages can be searched verbatim.

Error 1: AttributeError: 'GGUFWriter' object has no attribute 'write_header'

python -c "import sys; sys.path.insert(0,'./pylibs'); from gguf import GGUFWriter, GGUFReader; print([m for m in ('write_header','write_header_to_file','write_footer','write_tensors_to_file') if hasattr(GGUFWriter, m)]); print([m for m in ('get','get_field','get_tensor') if hasattr(GGUFReader, m)])"

Error 2: ValueError: cannot reshape array of size 0 into shape (3,)

Error 3: TypeError: list indices must be integers or slices, not str

Error 4: struct.error: 'i' format requires -2147483648 <= number <= 2147483647

Two more shapes are worth recording. Calling add_tensor_info without ever supplying data makes write_tensors_to_file() raise a bare AssertionError with an empty message — the log shows only the type. And calling the stages out of order raises ValueError: Expected output file to contain KV data, got WriterState.HEADER; the state names in that message (NO_FILE, HEADER, KV_DATA) tell you exactly which step you are on, which is more useful than the error itself.

Six checks before you ship

FAQ

Q: If the library cannot read its own output, is it unusable?

A: No. The alignment case is a wrong call, not a broken library — add_custom_alignment() keeps both sides at 64. What deserves suspicion are the silent ones (empty arrays, duplicate keys, trusted counts), because they never give you a second chance.

Q: Why not validate against a real GGUF model file?

A: Size and interpretability. The smallest useful model is hundreds of megabytes, and a real file has hundreds of fields, so when something is wrong you cannot point at the line that wrote it. A few hundred bytes that you wrote yourself makes the comparison meaningful. A real model is a good final regression, a bad debugging surface.

Q: Is a metadata string length stored as characters or bytes?

A: Bytes. I wrote three keys: cafe reports length 4, café reports 5 (four characters), and the two-character Chinese string reports 6. Validating the length field with len(s) is guaranteed to be wrong for non-ASCII input. It is the same root cause as the encoding layer: strings in the file are byte sequences, not character sequences. I compared five decode strategies on identical bad bytes in this post on decode error handlers, which is the natural companion read.

Q: Are the GGUF version number and the quantization type number the same numbering scheme?

A: No. The version is the file structure version (currently 3, reader accepts 2 and 3). The quantization type is the ggml_type enum (F32=0, F16=1, Q8_0=8, Q4_K=12 and so on). Both live near the header, but one is a uint32 format version and the other is a type code inside each tensor's info block; mixing them up reads the wrong data.

Closing

I set out to confirm one field's value and ended up with an eight-row table of "read back does not equal written". What these cases share is that no layer validates meaning. The writer only guarantees bytes reach the disk, the reader only guarantees it follows the header's declarations, and the gap between "what you wrote" and "what you think you wrote" belongs to nobody.

Structural claims like this show up everywhere once you look. YAML's type assignment silently turns no into False and 1:30 into 90; packaging silent failures let pip install succeed while you keep running old code. Read together, they form one line: the thing you stored is not the thing you get back.

There are no affiliate links in this article, and every result above is reproducible with the commands shown.

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home