spec/errors
Error codes
The single normative list of Text Tables error and warning codes. Codes are kebab-case (decision 0005).
Severity
- FAIL — a conforming parser MUST reject the file.
- WARN — a conforming parser MUST NOT reject the file; it SHOULD report the code and continue. Tools MAY refuse structural changes while a warning stands (see
column-count-mismatch).
Verify — behaviour under txtab verify:
— — unchanged;
→ FAIL — the warning becomes a failure;
never — stays a warning even in verify.
##File and first line
| Code |
Severity |
Verify |
Meaning |
prefix-invalid |
FAIL |
— |
P is empty, longer than 8 characters, contains a character outside printable ASCII, starts with a letter or digit, or contains a delimiter or quote character. |
kv-malformed |
FAIL |
— |
A key=value list (first line or key-value payload) has a token without = or an unterminated quote. |
value-invalid |
FAIL |
— |
A value is invalid for its key (e.g. header=2, storage=disk). |
key-unknown |
WARN |
— |
Unknown key; ignored and preserved. |
key-duplicate |
WARN |
— |
A key repeated in one line; last wins. |
key-misplaced |
WARN |
— |
A table key on the first line, or a file key on P table; ignored. |
version-unknown |
WARN |
— |
texttables= names a version the parser does not implement; read best-effort. |
first-line-not-ascii |
FAIL |
— |
Line 1 contains a non-ASCII character. |
encoding-mixed-inline |
FAIL |
— |
An inline table declares an encoding different from the file's and one of them is not ASCII-compatible. |
encoding-unknown |
WARN |
— |
Unknown ASCII-compatible encoding name; UTF-8 is used. |
encoding-invalid-bytes |
FAIL |
— |
Bytes not decodable in the effective encoding. |
encoding-mismatch |
WARN |
— |
encoding= disagrees with a BOM (of the file, a referenced file or a .col file); the BOM wins. |
##System lines
| Code |
Severity |
Verify |
Meaning |
keyword-malformed |
FAIL |
— |
The first token after P is neither -- nor a valid keyword. |
keyword-unknown |
WARN |
— |
Unknown keyword; ignored and preserved. |
column-in-file-block |
FAIL |
— |
column before the first P table. |
agg-in-file-block |
FAIL |
— |
agg-* before the first P table. |
link-in-file-block |
FAIL |
— |
link before the first P table. |
chart-in-file-block |
FAIL |
— |
chart / chart-<engine> before the first P table. |
note-address-in-file-block |
FAIL |
— |
A note with col, row or key before the first P table. |
directive-after-data |
FAIL |
— |
A directive other than table between a table's data and the next P table. |
meta-duplicate |
WARN |
— |
A meta-* key repeated in one block; last wins. |
##Tables
| Code |
Severity |
Verify |
Meaning |
tables-mismatch |
FAIL |
— |
The number of P table lines differs from tables= (or from 1 when it is absent). Always a failure: the file is incomplete or wrong. |
tables-missing |
FAIL |
— |
More than one P table line without tables= on the first line. |
table-missing-rows |
FAIL |
— |
P table without rows=. |
table-name-invalid |
FAIL |
— |
Table name= does not match [A-Za-z_][A-Za-z0-9_]*. |
table-name-duplicate |
FAIL |
— |
Two tables with the same name=. |
rows-mismatch |
WARN |
→ FAIL |
The actual number of data records differs from rows=. |
columns-mismatch |
WARN |
→ FAIL |
The physical column count differs from columns=. |
data-in-reference-table |
FAIL |
— |
A record in the block of a reference= table. |
reference-escapes-dir |
FAIL |
— |
reference= is absolute or resolves outside the file's directory (or the archive). |
reference-not-found |
WARN |
never |
The reference= target is missing on open; the table is metadata-only. |
storage-columns-without-dir |
FAIL |
— |
storage=columns without reference= to a directory. |
section-size-without-columns |
WARN |
— |
section-size= on a table that is not storage=columns; ignored. |
##Data records
| Code |
Severity |
Verify |
Meaning |
record-arity-mismatch |
FAIL |
— |
A record's field count differs from the physical column count. |
quote-none-delimiter-in-value |
FAIL |
— |
quote=none and a value contains the delimiter. |
quoted-value-raw-newline |
FAIL |
— |
A quoted value contains a raw line break; records are single-line. |
record-starts-with-prefix |
WARN |
— |
A record starts with P followed by a space, or equals P; the writer chose an unsafe prefix. |
##Columns
| Code |
Severity |
Verify |
Meaning |
column-missing-name |
FAIL |
— |
header=1 and a column has no name=. |
column-name-invalid |
FAIL |
— |
Column name= does not match [A-Za-z_][A-Za-z0-9_]*. |
column-missing-index |
FAIL |
— |
header=0 and a column has neither index= nor is computed. |
column-malformed-attribute |
FAIL |
— |
A malformed column attribute. |
column-unknown-attribute |
WARN |
— |
Unknown column attribute; ignored and preserved. |
column-name-header-mismatch |
WARN |
— |
header=1: no header cell equals the column's name= (no title=). |
column-title-header-mismatch |
WARN |
— |
header=1: no header cell equals the column's title=. |
column-duplicate |
WARN |
— |
Two column lines for the same column; last wins. |
column-count-mismatch |
WARN |
never |
The schema contradicts the data by count or position (index= beyond the width, more positioned columns than fields). Structural changes MUST be refused until reconciled. |
default-with-nulls |
WARN |
never |
default= set but the data has nulls. |
references-unresolved |
WARN |
— |
references= names a table or column that does not exist, or a table without a name. |
unit-unknown-column |
FAIL |
— |
unit=@<column> names an undeclared column. |
##Computed columns
| Code |
Severity |
Verify |
Meaning |
formula-references-computed |
FAIL |
— |
A formula references another computed column. |
formula-unknown-reference |
FAIL |
— |
A formula references a name that is not a stored column of the table. |
formula-parse-error |
FAIL |
— |
A formula does not parse. |
formula-index-forbidden |
FAIL |
— |
index= on a computed column. |
formula-requires-header |
FAIL |
— |
A computed column while header=0. |
computed-materialized-mismatch |
FAIL |
— |
materialized=1 without data, or data without materialized=1. |
computed-default-ignored |
WARN |
— |
default= or required= on a computed column; ignored. |
computed-stale |
WARN |
never |
A materialized value may not match the current formula. |
##Aggregates
| Code |
Severity |
Verify |
Meaning |
agg-unknown |
WARN |
— |
Unknown agg-<name>; ignored. |
agg-duplicate |
WARN |
— |
The same agg-<name> twice in a table; last wins. |
agg-arity-mismatch |
WARN |
never |
More values than physical columns. |
agg-type-mismatch |
WARN |
— |
Aggregate does not fit the column type. |
agg-mismatch |
WARN |
never |
A recomputed aggregate differs from the declared one. |
| Code |
Severity |
Verify |
Meaning |
sql-dialect-missing |
FAIL |
— |
sql-* line without a dialect token. |
sql-unknown-dialect |
WARN |
— |
Unrecognised dialect token; kept as is. |
sql-dialect-family |
WARN |
— |
Match kind family. |
sql-version-mismatch |
WARN |
— |
Match kind version-mismatch; --strict skips the line. |
sql-no-match |
WARN |
— |
No sql-* line matches the target dialect. |
ddl-column-mismatch |
WARN |
never |
DDL appears to disagree with the column set; best-effort detection only. |
##Notes and links
| Code |
Severity |
Verify |
Meaning |
note-malformed |
FAIL |
— |
A note does not tokenize. |
note-missing-text |
FAIL |
— |
A note without text=. |
note-row-and-key |
FAIL |
— |
A note with both row= and key=. |
link-malformed |
FAIL |
— |
A link does not tokenize. |
link-missing-href |
FAIL |
— |
A link without href=. |
link-missing-address |
FAIL |
— |
A link without col=, or without both row= and key=. |
link-row-and-key |
FAIL |
— |
A link with both row= and key=. |
note-unresolved |
WARN |
never |
A note address does not resolve; preserved. |
link-unresolved |
WARN |
never |
A link address does not resolve; preserved. |
link-duplicate |
WARN |
— |
Two link lines on one cell; last wins. |
link-unknown-column |
WARN |
— |
A link= placeholder names no stored or materialized column. |
link-template-malformed |
WARN |
— |
A link= template has an unterminated {. |
link-unsafe-scheme |
WARN |
never |
A final URL's scheme is not http, https or mailto; shown as text. |
##Charts
| Code |
Severity |
Verify |
Meaning |
chart-missing-type |
FAIL |
— |
A compact chart without type=. |
chart-missing-name |
FAIL |
— |
A compact chart without name=. |
chart-unknown-column |
FAIL |
— |
A channel names a column without a column line in the table. |
chart-missing-required-channel |
FAIL |
— |
The mark lacks a required channel. |
chart-vega-invalid-json |
FAIL |
— |
A chart-vega payload is not valid JSON. |
chart-duplicate-name |
WARN |
— |
Two charts with the same name= in a table; last wins. |
chart-unknown-type |
WARN |
— |
Unknown type= or chart-<engine>; ignored and preserved. |
chart-unknown-channel |
WARN |
— |
Unknown channel or modifier; ignored. |
##Archive and column storage
| Code |
Severity |
Verify |
Meaning |
zip-main-not-first |
FAIL |
— |
The first central-directory entry is not a .txtab main file. |
zip-main-bad-name |
FAIL |
— |
The main file is neither the archive name without .zip nor data.txtab. |
zip-unsupported-compression |
FAIL |
— |
An entry uses an unsupported compression method. |
zip-encrypted |
FAIL |
— |
Encrypted archive and no password (operational). |
zip-comment-not-utf8 |
WARN |
— |
The comment is not UTF-8. |
zip-comment-not-prefix |
WARN |
— |
The comment is not a valid Text Tables prefix. |
zip-comment-disagree |
WARN |
— |
The comment disagrees with the main file beyond truncation. |
col-file-missing |
FAIL |
— |
A physical column of a storage=columns table has no .col file. |
col-count-mismatch |
FAIL |
— |
The number of .col files differs from columns=. |
col-line-count-mismatch |
FAIL |
— |
A .col file's line count differs from rows. |
section-partition-error |
FAIL |
— |
Sections do not partition [0, rows) according to section-size=. |
section-boundary-mismatch |
FAIL |
— |
Section boundaries differ between columns. |
spec/errors.md on GitHub