Source-Aware Diagnostics⚓︎

The best table error tells the reader where to look. Not just which Python function failed, but which authored cell caused the problem.

Given the users exist
  | name | age | active |
  | Mira | old | maybe  |

A useful diagnostic points back to the table:

Field parser failed: invalid literal for int() with base 10: 'old'
(code=parser_failed, schema=UserTable, field='age', row=2, column=2, value='old').
Hint: Check the cell value or adjust the field parser for this syntax.

That message carries two kinds of information:

• human text that explains the failure
• structured details that tools can inspect

What the fields are for⚓︎

schema_name tells you which contract was parsing the table. field_name identifies its Python declaration, while field_label preserves the authored label. source_uri, row, and column point to the authored cell. source_value preserves what the author wrote, logical_value records what a transformer produced, and code gives tooling a stable category. Compatibility TableError properties such as schema, field, and value remain available.

Several errors at once⚓︎

During authoring, it is often better to report independent problems together:

Table contains 2 errors:
  1. Field parser failed: invalid literal for int() with base 10: 'old' (code=parser_failed, schema=UserTable, field='age', row=2, column=2, value='old').
  2. Field parser failed: Expected one of ['false', 'true'] (code=parser_failed, schema=UserTable, field='active', row=2, column=3, value='maybe').

See how to build an error from a source cell and how to inspect an aggregate of collected errors.

Tools that should not raise can use Schema.validate() and Diagnostic Model v1.

This helps feature authors fix a table in one pass instead of chasing one failure per test run.