GGUF Metadata: Eight Fields That Read Back Wrong
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.
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:
write_header_to_file()writes magic, version, tensor count and KV countwrite_kv_data_to_file()writes every metadata keywrite_tensors_to_file()writes the tensor info table, pads to alignment, then writes tensor dataclose()finishes the file
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 written | File size | data_offset | Reads back |
|---|---|---|---|
| Not written (default 32) | 160 B | 128 | yes |
general.alignment=64 only | 192 B | writer still pads to 32 | no, reshape error |
add_custom_alignment(64) | 256 B | 192 | yes |
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'
- Symptom: a four-step write copied from a tutorial dies on the first line;
write_footerfails identically, and so doesreader.get(). - Cause: in 0.19.0 the methods carry a
_to_filesuffix and the write is split into header, kv and tensor stages; there is no standalone footer step. - Fix: call
write_header_to_file(), thenwrite_kv_data_to_file(), thenwrite_tensors_to_file(), thenclose(); read withget_field(). Checking names withhasattris faster than reading tutorials:
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,)
- Symptom: the write succeeds and the file is non-empty, but reading fails inside
_build_tensors;size 0means the offset landed past the end of the file. - Cause:
add_uint32("general.alignment", 64)changes only the metadata. The writer still pads withdata_alignment=32while the reader looks for a multiple of 64, so the two sides disagree by 32 bytes. - Fix: use
add_custom_alignment(64), which sets the internal alignment and the key-value together. Re-check three things afterwards: the file grows,data_offset % alignment == 0, and the tensor data reads back.
Error 3: TypeError: list indices must be integers or slices, not str
- Symptom:
reader.tensors["blk.0.weight"]raises immediately. - Cause:
tensorsis a list, not a dict. - Fix: build a name map first or index by position; for batch work use
{t.name: t for t in reader.tensors}.
Error 4: struct.error: 'i' format requires -2147483648 <= number <= 2147483647
- Symptom: the
add_arraycall looks fine and the failure appears later insidewrite_kv_data_to_file(), with_pack_valand_packon the stack. - Cause: the array subtype is inferred from the first element, and Python
intis always judgedINT32, which cannot hold values above 2^31-1. - Fix: use the scalar methods with an explicit width (
add_uint64,add_int64), or store oversized numbers as strings. Do not rely on inference.
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
- Alignment: only ever use
add_custom_alignment(); assertdata_offset % alignment == 0after writing. - Counts: compare
len(reader.tensors)with the header'stensor_count; a mismatch means the file is broken. - Empty arrays: test any "optional list" for emptiness before writing — an empty list means the field does not exist.
- Duplicate keys: raise the gguf logger to WARNING, otherwise the overwrite notice is invisible.
- Dimensions: use
data.shapefor display; useshapeonly when you need the file's own order, and remember that for quantized tensors it is an element count. - Integrity:
file size >= data_offset + sum(n_bytes)is more reliable than any error message.
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.