[0.1 draft] [guide 15 · spec 15 pages]

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.

SQL

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.
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