Diagnostics glossary

Sample line. [author-error] @field 'firstName' did not match any column on table 'customer'; did you mean: FIRST_NAME, LAST_NAME, EMAIL.

Cause. Author-correctable: a name typo, a missing @table somewhere it’s needed, a directive pointed at something the jOOQ catalog or SDL registry doesn’t know about. When the lookup is against a closed set, the message includes a did you mean: …​ hint with up to five candidates ranked by Levenshtein distance.

Next step. The fix is in the schema or the consumer code (a column rename, an FK declaration, a <namedReference> entry); no Graphitron-internal change is needed. If the message includes did you mean: …​, the relevant attempt-kind below names the resolution rule. When you can’t tell whether an error is [author-error] or [invalid-schema], the rule of thumb is "could a column rename in the SDL fix it?" Yes → [author-error]. No → [invalid-schema].

Sample line. [invalid-schema] @asConnection on a non-@splitQuery field that returns a paginated child or [invalid-schema] lookup fields must not return a connection.

Cause. The directive combination cannot work, period. Two sub-shapes:

Next step. Drop or replace one of the directives, or restructure the schema so the combination doesn’t arise. Renames don’t help; this is a hard "no". The directive pages in the directive reference document the admitted directive combinations per directive.

Sample line. [deferred] split-batch emitter does not yet support @condition with a join step — see graphitron-rewrite/roadmap/condition-join-step.md.

Cause. Recognised but not yet generator-supported. The classifier understands what the schema asks for, the rewrite roadmap tracks the work, but emission is stubbed until the relevant plan ships.

Next step. Either drop the unsupported shape (and revisit when the plan ships), or contribute the missing emission to the rewrite. The roadmap path on the message names the variant class or feature shape; the emit-block reasons further down this page describe each shape that currently lands here.

Sample line. [author-error] @field 'firstName' did not match any column on table 'customer'; did you mean: FIRST_NAME.

Cause. The @field directive’s name: argument did not match any column on the @table-bound parent. Typical typos: case (firstName vs FIRST_NAME) or a stale rename (column dropped at the database side, schema not updated).

Next step. Correct the name: argument, or update the database schema and regenerate the jOOQ catalog if the column was supposed to exist. @field directive reference covers the column-name resolution rules.

Sample line. [author-error] @table 'CUSTOMER' did not match any table in the catalog; did you mean: customer.

Cause. The @table directive’s name: argument did not match any table in the jOOQ-generated catalog. Candidates are tables under the configured <jooqPackage>.

Next step. Correct case or schema prefix. If the table is genuinely missing, regenerate the jOOQ catalog from the database first. @table directive reference covers the resolution rules.

Sample line. [author-error] @reference key 'customer_address_fkey' did not match any FK on table 'customer'; did you mean: customer_address_id_fkey.

Cause. The @reference directive’s key: argument did not match any FK declared on the parent table. Candidates are the FK constants on the relevant table’s Keys class.

Next step. Correct the constraint name. If the FK exists in the database but not in the catalog, regenerate jOOQ. If the FK doesn’t exist, declare it (ALTER TABLE …​ ADD FOREIGN KEY) or pin the join with table: instead of key:. @reference directive reference covers both pinning shapes.

Sample line. [author-error] @service method 'findCustomers' not found on com.example.CustomerService; did you mean: findCustomer.

Cause. The @service (or @externalField, @tableMethod) directive’s methodName: argument (or the field-name default) did not match any static method on the resolved class. Candidates are the public static methods on that class with matching arity.

Next step. Correct the method name or rebind via argMapping: if the parameter list shifted. How-to: Wire external Java code covers the FQCN + method-name contract.

Sample line. [author-error] @sourceRow method 'liftKeys' not found on com.example.Lifters; did you mean: liftKey.

Cause. The @sourceRow directive’s methodName: argument did not match any static method on the resolved class. Candidates are the lifter-shape static methods ((Set<Key>) → Map<Key, Value>) on that class.

Next step. Correct the method name. @sourceRow directive reference covers the lifter signature.

Sample line. [author-error] @enum constant 'PENDING' not found on com.example.Status; did you mean: PENDING_REVIEW.

Cause. A jOOQ-typed @enum mapping referenced a Java enum constant the resolved enum class doesn’t carry.

Next step. Correct the constant name, or update the jOOQ catalog if the database enum changed.

Sample line. [author-error] @nodeId typeName 'customer' did not match any GraphQL type; did you mean: Customer.

Cause. A @nodeId directive’s typeName: argument (or a similar refType lookup) did not match any GraphQL type in the assembled SDL.

Next step. Correct case or pull in the missing schema file. @nodeId directive reference covers the typeName resolution.

Sample line. [author-error] @node keyColumns 'customer_id' did not match a column on table 'customer'; did you mean: CUSTOMER_ID.

Cause. A @node directive’s keyColumns: argument named a column the bound table doesn’t carry.

Next step. Correct case (jOOQ-generated identifiers are usually upper-snake) or update keyColumns: after a schema change. @node directive reference covers the keyColumns: contract.

Sample line. [author-error] @mutation typeName 'CREATE' is not a supported DML kind; did you mean: INSERT.

Cause. A @mutation directive’s typeName: argument did not match the closed set of supported DML kinds.

Next step. Use one of the supported values (INSERT, UPDATE, DELETE, UPSERT). @mutation directive reference covers the supported kinds.