JNT diagnostics reference
Every diagnostic JauntyQ can report, generated from the registry in
src/Extrode.JauntyQ.Generator/JauntyDiagnostics.cs. Format: JNTxxxx where the
first digit is the category. An Error blocks code generation for that
query/table; a Warning still emits code.
0xxx, Generator Internal
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT0001 | Generator Internal Error | Error | JauntyQ itself threw. Not a fault in your SQL, schema or configuration. It exists because Roslyn's own story for a generator that throws is CS8785, which is a warning: the build continues, every type the generator would have emitted is simply absent, and you see only the CS0246s that follow. The message names the stage that failed and the exception; the generated output may be incomplete or entirely missing depending on which stage it was. Please report it. |
1xxx, SQL Parsing
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT1001 | Unsupported SQL Construct | Warning | The tokenizer/parser hit a construct it doesn't model explicitly. Usually harmless, most SQL passes through verbatim. UNION and unsupported subqueries are excluded from this generic warning; see JNT1006/JNT1007. |
| JNT1002 | Unterminated Token | Error | A block comment (/* ...), bracket- or quote-delimited identifier ([..., "..., `...) or string literal ('...) ran to end-of-file with no closing delimiter. Fix the file. If the literal looks closed to you and you write MySQL, check for \', JauntyQ implements only the ANSI '' escape, and the message says so when it finds one. |
| JNT1003 | Input Too Large | Error | The .sql file exceeds SqlTokenizer.MaxInputLength (1 MiB). Split the file or check for accidental content. |
| JNT1004 | Unsupported Character | Error | The SQL contains a character the tokenizer does not recognize (e.g. $, \). JauntyQ refuses to parse rather than risk a silently wrong model. Remove the character or rewrite the construct. |
| JNT1005 | Nesting Too Deep | Error | Parentheses nest beyond SqlTokenizer.MaxNestingDepth (1000). The recursive-descent parser is O(n²) in depth, so JauntyQ refuses pathologically deep input (almost always a generated-SQL or copy-paste error) rather than let a single file hang the build. |
| JNT1006 | Unsupported UNION | Error | UNION/UNION ALL is not supported: the generator only models the first branch's column shape, so a second branch with different nullability could silently generate code that reads NULL as non-nullable and throws at runtime. Split into separate queries, or model the combined result as an application-level merge. |
| JNT1007 | Unsupported Subquery | Error | A nested SELECT that isn't a WHERE-clause [NOT] IN (SELECT ...)/[NOT] EXISTS (SELECT ...) predicate (a scalar subquery in the projection list, or a derived table in FROM) falls through to the enclosing statement's ordinary parsing instead of being lifted as its own scope, so the outer query's shape may already be misparsed. Rewrite using a JOIN, a WHERE-clause IN/EXISTS predicate, or a CTE. |
| JNT1008 | Multiple Statements In One File | Error | The file holds more than one top-level statement (a ; followed by more SQL). JauntyQ generates one method per file from one statement: a second SELECT's tables and columns are merged into the first statement's model, and a second statement after an INSERT/UPDATE/DELETE is dropped entirely, so the generated mapper matches neither statement. Split each statement into its own .sql file. |
| JNT1009 | Unsupported Syntax | Error | Syntax the parser has no grammar for, reported as such rather than as a schema problem. Currently: LATERAL joins, CROSS APPLY/OUTER APPLY, and PostgreSQL's DISTINCT ON (...). Split out of JNT2001, which was reporting both "this relation is not in your schema" and "this keyword is not in my grammar", for LEFT JOIN LATERAL the parser read the keyword as the joined table's name, so the consumer was told a table they had never written was missing from their schema. The two failures need opposite responses from the reader, so they no longer share a code. See supported-sql.md for the accepted surface. |
2xxx, Schema Validation
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT2001 | Table Not Found | Error | Query references a table absent from the schema snapshot. Re-run jauntyq schema pull or fix the table name. |
| JNT2002 | Column Not Found | Error | Query references a column absent from the resolved table. |
| JNT2003 | Ambiguous Column | Error | An unqualified column name matches more than one joined table; qualify it with an alias. |
| JNT2004 | Illegal Identifier | Error | A table/column/alias/parameter name can't form a valid C# identifier after DialectMapper.ToPascalCase. |
| JNT2005 | Stored Procedure Not Found | Error | -- @call <Proc> names a procedure absent from the schema snapshot's procedures section. |
| JNT2006 | Entity/Row POCO Name Collision | Error | Two tables would generate identical entity or row-POCO class names. |
| JNT2007 | Unmapped Column Type | Warning | DialectMapper.MapDbTypeToCSharp fell through to object for this column's db type, no C# type mapping exists. |
| JNT2008 | Duplicate Generated File | Error | Two .sql files produce the same generated file name, compared case-insensitively as Roslyn's AddSource does (e.g. getUsers.sql and GetUsers.sql in one folder, possible on a case-sensitive filesystem). Left unchecked this crashes the whole generator (CS8785); rename one so the generated names differ by more than case. |
| JNT2009 | Duplicate Sequence Accessor Name | Error | Two sequences whose PascalCased names collide would generate the same accessor method; only the first is emitted. Rename one. |
| JNT2010 | Duplicate Entity Accessor Name | Error | Two or more tables whose PascalCased names collide all generate the same db.<Entity> accessor; only the first table's auto-CRUD is emitted and the rest are invisible. Rename the tables, or write their queries by hand. |
| JNT2011 | Duplicate Column Property Name | Error | Two result columns of a stored procedure map to the same generated property, which the Result DTO cannot declare twice. Alias one distinctly in the procedure's own SELECT. |
| JNT2012 | Reserved Parameter Name Prefix | Error | A .sql query parameter uses the __ prefix, which is reserved for JauntyQ's own bookkeeping identifiers (__conn, __cmd, __reader, __weOpened and others). Such a name can silently collide with generated code. Rename it without the leading double underscore. A single leading underscore is fine. |
| JNT2013 | Duplicate Parameter Name | Error | Two stored-procedure parameters map to the same generated C# parameter, DialectMapper.ToPascalCase strips separators, so order_number and OrderNumber both become orderNumber. The generated method cannot declare it twice, and no rename by the generator can resolve it. Rename one in the procedure definition. |
| JNT2014 | Table Skipped For Colliding Column Names | Warning | Two of a table's columns map to the same generated property, so no row type or auto-CRUD can be emitted and the table is absent from the generated API entirely. Warning rather than error so an unused table with such a pair does not fail the build. Rename one column, or alias it distinctly in a hand-written query. |
| JNT2015 | Table Skipped For Unquotable Identifier | Warning | The table's name, or one of its column names, cannot be written unquoted: a keyword JauntyQ's own SQL parser reserves, a word the target engine reserves in that position, an illegal character, or (PostgreSQL only) a mixed-case name an unquoted reference would fold to lower case. Auto-CRUD is skipped and the table is absent from the generated API. Warning rather than error so an unused table does not fail the build. Rename it, or write its queries by hand with the identifier quoted. The per-engine reserved-word lists behind this are the verdict of a live probe against PostgreSQL 16, MySQL 8.0, MariaDB 11.8, SQL Server 2022 and SQLite 3.45, see DialectReservedWords.cs. |
| JNT2016 | Duplicate Enum Member Name | Error | Two members of a captured database enum fold to the same C# identifier, 'in progress' and 'in-progress' both become InProgress, and '' and '-' both become _. The generated enum cannot declare the member twice, and renaming one in the generator would silently diverge from the value the database stores. Both offending values are named in the message. Rename one member in the database. |
| JNT2017 | Enum Type Name Collision | Error | A captured enum's generated type name collides with another generated type: a row type, another enum, one of the emitted {EnumName}Values companions, or the shared JauntyQEnumValueException. A table named order_status_values alongside an enum order_status is the reachable case. Renaming silently is the anti-pattern JNT2015 exists to end, so this is an error. Rename the table or the enum. |
| JNT2018 | Non-Atomic Key-Targeted MySQL Upsert | Warning | The table carries a UNIQUE constraint other than the key the upsert resolved, so MySQL's ON DUPLICATE KEY UPDATE, which names no conflict target and matches whichever UNIQUE the insert violates, would not agree with the key postgres/sqlite ON CONFLICT (cols) and sqlserver MERGE ... ON name explicitly. JauntyQ therefore emits a key-targeted UPDATE ... ; INSERT ... SELECT ... WHERE NOT EXISTS pair instead. Two statements are not atomic, and a transaction does not make them so, concurrent upserts of the same new key can fail with 1062 (both pass the existence check), deadlock with 1213 (one session's insert-intention lock meets the other's gap lock from the UPDATE), or silently write nothing and return 0 (another session commits the row between this call's UPDATE and its INSERT). Retry on 1062/1213 (the call is idempotent) or drop the competing constraint; a 0 return is not by itself evidence of the lost write, since an unchanged re-run also returns 0 under UseAffectedRows=true. Any UNIQUE whose column set differs from the key counts as competing, with one exception: a full-column superset of the key cannot fire independently of it (violating (id, tenant) requires duplicating id) and is not competing. An index with a MySQL prefix key part (captured from SUB_PART as IndexSchema.HasPrefixKeyPart) is always competing, whether a superset (UNIQUE (id(3), tenant)) or a restatement of the key's own columns (UNIQUE (id(3)) beside a full-column key on id), it fires on rows sharing only the prefix. A UNIQUE with an expression key part (MySQL functional index, captured as IndexSchema.HasExpressionKeyPart with only the real-column subset in Columns) always competes, it constrains rows through an expression the key's columns say nothing about, and before 2026-07-30 it was excluded at capture and therefore invisible to this check. Single-UNIQUE tables are unaffected and keep ON DUPLICATE KEY UPDATE. |
| JNT2019 | Upsert Skipped For Prefix-Only Unique Key | Warning | The only constraint that could serve as the table's upsert key is a UNIQUE over a column prefix (MySQL UNIQUE (email(5)), captured from SUB_PART as IndexSchema.HasPrefixKeyPart), either the sole fallback UNIQUE for an identity-only PK, or the PRIMARY index itself (PRIMARY KEY (name(10))). Such an index enforces uniqueness over the truncated prefix, so the engine matches rows sharing only that prefix, not the full value an Upsert(...) signature implies, and no emitted form, atomic or two-statement, can honor the contract. No Upsert is synthesized (the table's other CRUD is unaffected). Add a full-column UNIQUE constraint or a bindable primary key, or write the upsert by hand. A schema snapshot without index entries (e.g. migration simulation) carries no prefix evidence and is never refused. |
| JNT2020 | Upsert Skipped For Expression-Only Unique Key | Warning | The only constraint that could serve as the table's upsert key is a UNIQUE with an expression key part (UNIQUE (lower(email)), captured as IndexSchema.HasExpressionKeyPart with only the real-column subset of its key in Columns). The engine matches conflicts on the expression's value, which no generated method can bind a parameter to, and the snapshot does not carry the expression at all, so such an index can never be the upsert key. No Upsert is synthesized (the table's other CRUD is unaffected). Add a full-column UNIQUE constraint or a bindable primary key, or write the upsert by hand. When a prefix-only refusal (JNT2019) and this one could both apply, only JNT2019 is reported. Before 2026-08-01 this skip was silent, the reading such tables had when expression indexes were excluded at capture entirely (pre-2026-07-30). |
| JNT2021 | Write To View | Error | An INSERT/UPDATE/DELETE targets a relation captured as a view (isView: true). Views enter the snapshot so they can be read; they are captured read-only, so no write is generated for one. Keyed on the write's target relation only, an UPDATE against a base table whose predicate joins or subqueries a view is fine, and a SELECT from a view is the case views exist for. Error rather than a silent skip because the consumer authored the statement deliberately: skipping it would emit a method whose SQL the engine rejects at runtime, and warning would let that method be called. Write to the underlying table instead. |
| JNT2022 | Lossy Identifier Rename | Warning | A table or column name contains a letter or digit outside ASCII, which generated names drop: größe becomes the property GrE, café becomes Caf, 日本語 becomes _. The code compiles and nothing collides, so JNT2011/JNT2014 never see it, but the property is spelled as a different word from your column. Rename the column, or alias it to an ASCII name in a hand-written query. |
| JNT2023 | Function Name Collision | Error | Two captured functions fold to one generated method name, or a function's name collides with a table, enum or sequence accessor. PostgreSQL overloads are the common case: f(int) and f(text) are distinct functions whose parameter types often map to the same C# types, so C# overloading cannot carry them. Error rather than a skip because nothing can be emitted for either side, choosing one silently would make which function a call site reaches depend on emission order. Rename one function, or exclude it from capture. |
| JNT2024 | Unmappable Function Signature | Warning | A captured function has a parameter or return type with no C# mapping, so no method is emitted for it. The rest of the schema generates unaffected, one unmappable function does not cost you the others. Hand-write the call, or change the function's signature to a mappable type. |
| JNT2025 | Table-Valued Parameter Not Supported | Warning | A captured procedure takes a SQL Server table-valued parameter. No method is emitted: binding a TVP needs SqlParameter.SqlDbType = SqlDbType.Structured and SqlDataRecord, which the generated abstract DbParameter path cannot reach. The message prints the TVP type's full column list, so you have the shape needed to hand-write the call with IEnumerable<SqlDataRecord>. Previously this generated object with JNT2007, a method that compiled and could not work. TVP support is specified and deferred; if you are hitting this, that is the signal that moves it. |
| JNT2026 | Duplicate Return-Value Parameter | Error | A captured procedure declares more than one parameter with direction ReturnValue. A procedure has exactly one return status, so at most one of them could ever carry a value and nothing defines which. No method is emitted. Keep one and give the others direction Out. This is only reachable from a hand-authored or externally produced snapshot: jauntyq schema pull never emits the direction. |
| JNT2027 | Auto-CRUD Method Skipped | Warning | An auto-CRUD query JauntyQ generated for one of your tables fails JauntyQ's own validation, so that one method is not emitted. This is a JauntyQ bug, not a problem with your schema: the message names the method, the table and each validation error; please report it with the table's definition. Until it is fixed, write the query by hand at the path the message gives, quoting any identifier the error names. Before this diagnostic the skip was silent: a SQL Server or SQLite table named lateral lost GetAll and GetById with nothing in the build output. |
3xxx, Query Shape / Projection
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT3001 | Empty Query | Warning | The .sql file is empty or has no SELECT columns to project. |
| JNT3002 | SELECT * Forbidden | Error | SELECT * is rejected, list columns explicitly so the generated shape is stable. |
| JNT3003 | Invalid Directive Combination | Error | Two directives on the same query conflict (e.g. -- @stream with -- @first). |
| JNT3004 | Expression Projection Missing Alias | Error | A computed SELECT expression has no AS alias, so the generator has no property name to emit. |
| JNT3005 | Expression Type Unresolved | Error | A computed expression's C# type can't be inferred; declare it with -- @type <alias> <type>. |
| JNT3006 | Unknown Type Directive Alias | Error | A -- @type directive names an alias that doesn't match any projection item. |
| JNT3007 | IN-Subquery Column Count | Error | An IN (SELECT ...) subquery projects more than one column. |
| JNT3008 | Unrecognized Directive | Warning | A -- @word comment looks like a directive but parsed as nothing: a value-taking directive written bare (-- @each with no parameter name) or a one-edit typo of a known name (-- @frist). The line stayed a plain comment and had no effect. Ordinary @word comments (-- @author) never trigger this. |
| JNT3009 | Duplicate Result Column | Error | Two SELECT/RETURNING items map to the same generated property after DialectMapper.ToPascalCase (id as X, y as X, the case-only as x, as X, or the separator fold my_col/myCol). The row type can't declare the member twice (CS0102); give each item a distinct alias. |
| JNT3010 | Mirrored Query Not Comparable | Warning | A file declares -- @mirrors <Query> but the pairing cannot be compared, so no drift verdict is possible: the target name resolves to no query in the corpus (typo, renamed file, not in AdditionalFiles), a bare method name is ambiguous across two entities (qualify it Entity.Method), the target produced no query model (it failed to parse or validate, or it binds a stored procedure), the target is the declaring query itself, or a WHERE-clause column on either side does not resolve to a schema column (a CTE virtual column, say). Reported rather than silently skipped, and rather than falling back to raw text, a text comparison would invent drift out of a spelling difference, and one false positive kills an opt-in check. Fix the target name or qualify the column, or remove the directive. |
| JNT3011 | Duplicate Directive | Warning | A non-repeatable directive appears more than once in one .sql file. Every directive except -- @type and -- @each stores into a single field, so the later line overwrites the earlier one, previously without a word, which made two contradictory -- @result lines, or two -- @allow-sort reasons where only the second is in force, invisible in both the SQL and the generated code. Later still wins; the message names the value that was discarded and the one that took its place. A repeat carrying the same value (including a repeated flag such as -- @first) gets the milder wording, since nothing was lost. Bare value-taking lines are not occurrences: -- @call with no name is declined as JNT3008 and does not make a later real -- @call look like a repeat. |
4xxx, Parameter Binding
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT4003 | Parameter Type Unresolved | Error | @param's C# type couldn't be inferred from a bound column; declare it via -- @params name:type. |
| JNT4004 | Duplicate Parameter | Error | The same @name appears twice in a -- @params directive. |
| JNT4005 | Scoped Table Reached Without Its Scope Parameter | Error | A table declared in jaunty.scope.json is reached without a proof that it is filtered by its scope column (spec 021). A proof is a top-level AND condition of exactly <ref>.<column> = @param, in the place SQL applies it: WHERE or an inner join's ON for a table read in FROM or an inner JOIN; the table's own ON (or a later RIGHT JOIN's ON) on the nullable side of an outer join; WHERE only in a FULL JOIN; WHERE for an UPDATE or DELETE target; a parameter in the column list for an INSERT target. OR, NOT, a literal, another column, IS NULL and IN (@ids) are not proof. CTE bodies and WHERE subqueries need their own. One error per unproven reach, naming it and the fix. The query is never rewritten; -- @unscoped <reason> accepts it. |
| JNT4006 | Unnecessary Unscoped Acceptance | Warning | A query declares -- @unscoped <reason> but reaches every scoped table with its scope parameter, so the directive accepts nothing: remove it. The message repeats the stated reason. Silent when the analysis reached no verdict: no scope file, a scope file with no usable entry, or a query that already failed validation. Warning, not Error, for the same reason as JNT8012. |
| JNT4007 | Scoped Upsert Not Generated | Info | Auto-CRUD generates no Upsert for a MySQL table that the scope file scopes. ON DUPLICATE KEY UPDATE has no WHERE, so a key collision with another scope's row would overwrite that row. Use Insert and Update, or write the upsert by hand and prove the scope in it. PostgreSQL, SQLite and SQL Server get a scoped Upsert instead. |
5xxx, Value Safety
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT5001 | String Literal Exceeds Column Length | Error | A literal string value in the SQL is longer than the target column's MaxLength. |
| JNT5002 | Numeric Literal Out Of Range | Error | A literal numeric value can't fit the target column's numeric type/precision. Also covers a value the engine accepts but silently rewrites: a fractional literal beyond the column's scale, and a SQL Server bit given anything but 0 or 1 (stored as 1). |
| JNT5003 | Literal Type Mismatch | Error | A literal is the wrong kind of value for the column, not merely too long or too large, the server rejects the statement outright. Today: a numeric literal against a PostgreSQL bit/bit(n), which is a bit string and needs B'1010' form. |
6xxx, Configuration
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT6001 | Schema Missing | Error | No schema snapshot found and no db/ddl/*.sql DDL source either. Run jauntyq schema pull, or see db/ddl/*.sql + <JauntyQDialect> (JNT9003). |
| JNT6002 | Multiple Schema Snapshots | Warning | More than one *.schema.json was passed as AdditionalFiles. The ordinal-lowest path wins deterministically; the message names every candidate. Remove the extras (or exclude them from <AdditionalFiles>) so the schema source is unambiguous. |
7xxx, Dialect
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT6003 | Invalid Acceptance File | Warning | A structural problem in jaunty.accept.json, the sidecar that accepts an unindexed auto-CRUD scan per column (spec 016): the file is not valid JSON, more than one *.accept.json was passed as AdditionalFiles (ordinal-lowest wins, the message names every candidate, and the others are not merged), an entry is missing its table, column or reason, an entry names a table or column the snapshot does not have (a typo, or an entry that outlived a dropped column), or the same column is accepted twice (the first entry is the one in force). A rejected entry accepts nothing, so the JNT8004 it was meant to cover is still reported, a half-read entry quietening a warning would make a typo cheaper than getting it right. An entry that is well-formed but no longer needed is JNT8012, not this. Warning rather than Error: a mistake in the file written to quieten the build must not be louder than the warnings it was written to quieten. |
| JNT6004 | Invalid Scope File | Warning | A problem in jaunty.scope.json, the sidecar that declares tables scoped by a column (spec 021): the file is not valid JSON or is the literal null, more than one *.scope.json was passed as AdditionalFiles (ordinal-lowest wins, the others are not merged), an entry is missing its table or column, names a table or column the schema does not have, names a column that cannot be bound from a parameter (part of the primary key, identity, computed or rowversion), or repeats an earlier entry. Every dropped entry leaves its table unscoped, and the message says so. Warning rather than Error, as for JNT6003. |
| JNT7001 | Identity Return Unavailable | Error | -- @identity was used but the table/dialect combination can't return the generated key. |
| JNT7002 | Construct Unavailable On Dialect | Error | A RETURNING clause or data-modifying CTE was used on sqlserver/mysql, neither of which supports it (MariaDB via the mysql dialect string does support RETURNING 10.5+/13.0+, this intentionally over-flags that case to stay safe on stock MySQL). |
| JNT7003 | Unknown Dialect | Error | schema.Dialect isn't one of sqlserver/postgres/sqlite/mysql, check DialectMapper.IsKnownDialect. |
8xxx, Performance
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT8001 | Possible Cartesian Product | Warning | A join has no ON/equality condition connecting the two tables. |
| JNT8002 | Non-Sargable Predicate | Warning | A WHERE clause wraps an indexed column in a function/expression, defeating index seeks. |
| JNT8003 | Leading-Wildcard LIKE | Warning | LIKE '%value' can't use a standard B-tree index. |
| JNT8004 | Unindexed Filter Column | Warning | A filter/join column has no covering index (composite indexes are checked positionally: a non-leading column is "covered" only when every column ahead of it in the same index is also filtered in this query). On a hand-written query, accept it deliberately with -- @allow-unindexed <reason>. On an auto-CRUD query there is no file to annotate, so the message names the exact .sql path that would override the generated method, and, since spec 016, the jaunty.accept.json entry that accepts the scan without giving up schema tracking. Only the GetBy<Fk> loader family can raise this: GetAll has no filter, and GetById/Update/Delete filter the full primary key. |
| JNT8005 | Duplicate Query | Warning | Two or more generated methods compile to byte-for-byte identical SQL; consolidate them. |
| JNT8006 | Join Not A Foreign Key | Warning | A join's column pair matches no declared foreign key between the two tables (exact per-pair match, either direction). Usually a wrong-column join (a bug) or an unmodeled relationship. Skipped when the snapshot carries no foreignKeys, or when either side resolves to a CTE/subquery/table absent from the schema. Composite FKs are stored one row per column pair, so a pair-by-pair join matches and is not flagged. |
| JNT8007 | Unindexed Order By | Warning | An ORDER BY names a column no index can order (not the leading column of any index, and not a non-leading column whose more-leading index columns are all constrained by a bound parameter in this query, any comparison operator, not only equality, which makes a range on the leading column a known false negative), forcing a runtime sort. Accept it deliberately with -- @allow-sort <reason>. Only plain base-column items are checked; ordinals (ORDER BY 1), expressions (ORDER BY lower(x)), projected aliases, primary keys, and snapshots without index metadata are skipped. |
| JNT8008 | Possible N+1 Access Pattern | Warning | Cross-query heuristic: a SELECT is a point lookup on a child table by an equality on every column of a declared foreign key (WHERE child.parent_id = @parentId), and the corpus also contains a parent-collection query over that FK's parent table (a multi-row SELECT, not a single-row PK lookup). Calling the child lookup once per parent row is 1 + N round-trips, fetch set-based instead: join the child into the parent query, or batch with WHERE parent_id IN (@ParentIds) under -- @each ParentIds, one query for all parents (see loading parents with their children; for a composite key the message keeps the generic IN (...), and for the COUNT/aggregate-per-parent variant it also offers a grouped aggregate join). Eager loading is not planned. Fires at most once per child lookup, naming one representative parent query. Never fires when the child is already set-based (IN on the FK column, or joins/reads the parent), when the parent query is a single-row PK lookup, or when the snapshot has no foreignKeys; composite FKs require all columns filtered (a partial match never fires) and self-referencing FKs are supported. Suppress an intentional per-row lookup the standard way: <NoWarn>$(NoWarn);JNT8008</NoWarn> or dotnet_diagnostic.JNT8008.severity = none in .editorconfig; or, for one query only and with the decision recorded in the file, -- @allow-n-plus-one <reason> (see JNT8013 and directives). |
| JNT8009 | Unstable Pagination | Warning | A query takes a page (LIMIT/OFFSET, including T-SQL's OFFSET … FETCH NEXT) but its ORDER BY covers no primary key and no complete unique index, so rows that sort equally have no defined relative order: the engine may return them differently on each execution, and a row can then appear on two pages or on none. Add a tiebreak on a unique column, usually the primary key. Checked per statement, so a page taken inside a CTE, the idiomatic paginate-then-aggregate shape, is checked against its own base columns, and a page taken by the final statement of a WITH is checked too (fixed 2026-08-03; before that the outer model never learned it paged, and both codes stayed silent on that shape). Silent when: the sort already covers a unique key; any ORDER BY item is an expression, ordinal, projected alias or unresolvable name (it may itself be unique, and the IR cannot tell); the statement joins, has more than one table, or has a GROUP BY (per-row uniqueness proves nothing about a fanned-out or collapsed result); this query's equality filters already pin one row; the statement is a predicate subquery; or the table carries no captured index metadata, in which case a non-PK unique tiebreak is unprovable rather than absent, DDL/migration-sourced tables have primary keys but no secondary unique indexes (see JauntyQGenerator.Part7.cs), so firing there would be a false positive on every such project. TOP n without OFFSET is not pagination and never fires. |
| JNT8010 | Unordered Pagination | Warning | A query takes a page with LIMIT/OFFSET and has no ORDER BY at all: the rows in a page are an arbitrary subset that can differ between requests. Strictly worse than JNT8009 and reported instead of it, never alongside. Needs no uniqueness proof, so unlike JNT8009 it still fires for a table with no captured index metadata. Silent under the same scope gates (join, multi-table, GROUP BY, predicate subquery) and when this query's equality filters already cover a unique key, which is what keeps the WHERE pk = @id LIMIT 1 point-lookup idiom quiet. |
| JNT8011 | Predicate Drift | Warning | Cross-query check, opt-in: a file declares -- @mirrors <Query> and its WHERE clause does not match that query's. The case it exists for is a paginated list and the count that sizes its pager, when one gains a filter the other lacks, the page contents stay correct while the total is wrong, and nothing else surfaces it. Compared are the WHERE clauses of the statement and of every CTE body, unioned (so the idiomatic paginate-inside-a-CTE list is comparable with a flat count), split at top-level AND into atoms and matched as a set with column references resolved against the schema first, so qualification (b.user_id vs user_id), keyword casing and atom order do not matter. ORDER BY, projection and LIMIT/OFFSET are not compared, a count query has none. Deliberately conservative: a top-level OR collapses the whole clause into one atom rather than being split, BETWEEN's own AND is not a splitter, and the match is textual after resolution, so a >= @x and @x <= a read as drift. Silent when the sets match and whenever no -- @mirrors is present; a pairing that cannot be compared is JNT3010, not silence. |
| JNT8012 | Unnecessary Unindexed Acceptance | Warning | Also reported for a jaunty.accept.json entry that no generated query used (spec 016), the message names the file, the table.column and the stated reason, and gives both remedies, because they differ: an index now covers the column (delete the entry), or a hand-written .sql has claimed that loader (move the acceptance into that file as -- @allow-unindexed). Not reported at all when auto-CRUD is off, since no entry could have been used. For the directive itself: a query declares -- @allow-unindexed <reason> but no filter column on it is unindexed, or -- @allow-sort <reason> but no ORDER BY column on it is unindexed, so the directive suppresses nothing. The message names the directive it is about, so a query carrying both says which one to remove. Almost always means the index it was waiting for now exists: remove the directive. Reported rather than tolerated because an exemption that outlives the condition justifying it is how an escape hatch becomes the default, left in place it stops hiding an accepted scan and starts hiding a future regression. Warning, not Error: a stale suppression is untidy, not wrong. |
| JNT8013 | Unnecessary N+1 Acceptance | Warning | A query declares -- @allow-n-plus-one <reason> but was never matched as an N+1 child lookup against any parent-collection query in the corpus, so the directive suppresses nothing: remove it. The message repeats the stated reason. Its own code rather than JNT8012 because the two rest on different evidence — JNT8012 (allow-unindexed) reads index metadata, this one reads the FK graph and the query corpus — and severity is configured per code, so silencing JNT8012 should not also silence this check. Usually means the parent-collection query it was written against is gone, or the child lookup has since become set-based. Silent when the snapshot declares no foreignKeys (the pass is inert, so nothing could have been suppressed). Warning, not Error, for the same reason as JNT8012. |
9xxx, Migrations
| Code | Title | Severity | Meaning |
|---|---|---|---|
| JNT9001 | Migration Statement Not Simulated | Warning | A migration statement MigrationParser has no explicit handling for at all (e.g. CREATE VIEW, CREATE PROCEDURE, an unmodeled RENAME, or an unrecognized constraint clause); the effective schema may be incomplete for it. Index DDL and permission statements (CREATE/DROP INDEX, GRANT/REVOKE) are explicitly recognized and silently ignored instead, they do not raise this diagnostic. |
| JNT9002 | Migration Invalid Against Schema | Error | A migration/DDL statement targets a table/column that doesn't exist (or already exists) in the schema being simulated. |
| JNT9003 | Missing or Unknown Dialect for DDL Schema Source | Error | db/ddl/*.sql files are present with no JSON snapshot, but <JauntyQDialect> isn't set to a recognized value (sqlserver/postgres/mysql/sqlite). |
| JNT9004 | Migration Risky Impact | Warning | A pending migration changed a column a query references (type, nullability, length, precision) without invalidating the query. Non-fatal; see jauntyq migrate impact for the full SAFE/RISKY/BREAKING report. |