Error kinds

An error kind is the stable name of a failure. An implementation reports the kind as a string. The message beside it is written for people and is not part of the contract: it can change between releases, and a test compares kinds only.

error-kind list version 1

The 22 kinds

“Produced by” names the verify step or the operation that reports the kind. Verify steps run in a fixed order, and a verifier that stops at the first failure reports the kind of that step, so two conforming implementations report the same kind for the same file. Section 9, Verify algorithm

**Table 1.** Error kinds, list version 1 (22)
#	Kind	Meaning	Produced by	Cases
1	`io`	The operating system refused a read or a write: a missing path, a permission, a short read, a full disk.	before verify	1
2	`invalid_header`	The file is shorter than 353 bytes, or the 257-byte header line does not match the header grammar: not ASCII, wrong magic, byte 256 not a line feed, or the wrong number or form of tokens.	§9 steps 1 and 2; §3.1	4
3	`unsupported_version`	The header or the footer names a format version other than 6.	§9 steps 2 and 3; §12.1	2
4	`invalid_footer`	The last 96 bytes are not a valid footer (magic or reserved bytes), or its offsets do not describe the file’s real layout: text section bounds, padding, or where the appendix sits.	§9 steps 3 and 5	7
5	`checksum_mismatch`	The SHA-256 of bytes 257 up to L − 96 differs from the digest in the footer.	§9 step 6; §6	2
6	`header_footer_mismatch`	A final header disagrees with the footer on `records`, `csdt_offset`, `csdt_size` or the digest, or the header is neither final nor a placeholder.	§9 step 4; §3.3	3
7	`record_count_mismatch`	The number of record lines differs from the footer’s `record_count`.	§9 step 8	1
8	`invalid_utf8`	The body, bytes 257 up to T, is not valid UTF-8.	§9 step 7; §4.1	1
9	`invalid_record`	A line is not a JSON object, has no string member `k`, or the appendix marker line is misplaced or missing.	§9 step 7; §4.1, §4.2	4
10	`json`	A line is not valid JSON, holds a lone surrogate, or a typed record fails its schema: a REQUIRED member is missing, or a member has the wrong JSON type.	§9 step 7; §4.3, §10.2	3
11	`appendix_invalid`	The embedded container fails a structural check: its magic, an unsupported version byte, its header, a section table outside the container, nonzero reserved descriptor bytes, a data range outside the container, or a tensor catalog section that cannot be read.	§9 step 9; §7.2, §7.3	8
12	`appendix_crc_mismatch`	A CRC32C check on the appendix fails: the section table’s checksum, a section’s checksum, or the footer’s copy of the container checksum.	§9 step 9; §7.3	2
13	`appendix_alignment`	`csdt_offset` is not a multiple of 64, an alignment exponent is above the accepted maximum, or the start of an aligned view is misaligned. There is no fallback that copies the bytes.	§9 step 5; §7.3	2
14	`appendix_legacy_version`	Merge was given an appendix in an older container version. Reading it is allowed; merging it is refused, so it is never converted without notice.	§8.1 precondition 2; §7.2	1
15	`section_type_mismatch`	A consumer bound an `embref` target under the Compact embedding profile, and the section is not a Compact section with the Compact record stride and data type.	§9 step 10	3
16	`dangling_embref`	A consumer bound a target that does not resolve: a section index or record index out of range, no appendix, or an `ext` target with no matching `csdt_ref` record.	§9 step 10	4
17	`merge_conflict`	Merge cannot combine the inputs: an appendix holds a tensor catalog section, or a section type is not registered.	§8.1 preconditions 3 and 4	2
18	`shard_unsupported_spec` Reserved	The shard request cannot be served by this pack: a request to shard by group (`cluster`), or a seed or listed entity that is not in the pack.	§8.3	0
19	`shard_quality_below_threshold` Reserved	The shard’s quality score, as defined in section 8.3, is below the caller’s minimum.	§8.3	0
20	`limit_exceeded`	A size the caller capped, or the platform’s address width, cannot hold a value: an input or inflated size above the caller’s cap, or an offset that cannot be an in-memory index (for example at or above 2^32 on a 32-bit platform). Values are never truncated.	§9 step 5	2
21	`unsupported`	The file is well formed but uses a feature this implementation does not have, such as an appendix payload class or data type it does not know.	§7.4; §15	1
22	`internal`	A defect in the implementation itself. Never the file’s fault.	—	0

Reading the list

17 kinds are named in the published specification. io, unsupported and internal are not: they describe the environment and the implementation, not the file. appendix_invalid and appendix_crc_mismatch are raised by the container checks of section 7.3.
A kind describes a pack, or the inputs of an operation, as data. A caller’s own mistake, such as a wrong argument type or an unknown option name, is reported by the host language’s ordinary means and is not a kind.
A lookup that can find nothing returns an empty value, not an error.
No conformance case expects internal. A run that reports it has found a defect in the implementation under test.
An implementation that meets a kind string it does not know reports it unchanged.