---
title: Diagnostics
description: Read stable TS codes, source spans, reasons, fixes, and model lint policy.
species: reference
---
# Diagnostics

Every typesql diagnostic carries a stable code, source location, reason, and concrete help when a mechanical repair is known. Human text can improve; automation should key on `TS####`.

```text
TS0400 at 3:10: unknown column `amunt`
help: did you mean `amount`?
```

## Code registry

| Codes | Class |
|---|---|
| `TS0001`–`TS0007` | Lexing, invalid characters, and document size |
| `TS0100`–`TS0105` | Parsing, unsupported syntax, depth, and malformed literals |
| `TS0200`–`TS0201` | Annotation erasure guarantees |
| `TS0300`–`TS0301` | Invalid or over-nested type expressions |
| `TS0400` | Unknown column |
| `TS0401` | Type mismatch |
| `TS0402` | `satisfies` failed |
| `TS0403` | Invalid cast |
| `TS0404`–`TS0405` | Function argument count or type |
| `TS0406` | Recursive function |
| `TS0407` | Set-operation column count |
| `TS0408` | JSON shape mismatch |
| `TS0409` | Alias column count |
| `TS0410`–`TS0412` | Masked cast, comparison, or flow |
| `TS0500`–`TS0501` | Target compilation or functional difference |
| `TS0600`–`TS0609` | Package reference, lock, artifact, hash, format, export, cycle, shadow, bounds, or unused import |
| `TS0700`–`TS0701` | Rewrite environment or bound |
| `TS0800`–`TS0803` | Logical-view environment, cycle, bound, or document |

## Machine form

Diagnostics are also JSON. Byte spans remain authoritative and render as 1-based line and column positions. Secondary labels point to related declarations when the cause is elsewhere.

## Model lint policy

A model can reclassify registered diagnostic codes in its first 20 comment lines:

```sql
-- lint:
--   TS0400: allow
--   TS0609: deny
```

The block accepts 1–16 unique codes. `allow` demotes a matching diagnostic to a warning. `deny` promotes it to an error. Unknown codes, duplicates, malformed entries, or more than one block refuse the model.