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 corrected className:); 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.

Cause. Recognised but not yet generator-supported. The classifier understands what the schema asks for, but emission is stubbed until support ships.

Next step. Either drop the unsupported shape (and revisit when support ships), or contribute the missing emission to the rewrite. The message states which shape is unsupported; 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) 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. The lifter must be a static method with the (Set<Key>) → Map<Key, Value> shape.

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.

Sample line. [author-error] @routine argMapping entry 'pCustomerId: input.custmerId': segment 'custmerId' does not exist on input type 'RentFilmInput'; did you mean: customerId.

Cause. The right-hand side of an argMapping entry names a GraphQL slot and then walks into nested input fields. One message serves every directive that accepts an argMapping (@service, @condition, @routine, @tableMethod) because the path namespace is the same at all of them; only the site prefix differs. Two shapes reach it: a head segment that names no slot in scope, which lists the slots that are, and a later segment that names no field on the input type at that depth, which suggests the near miss.

Next step. Correct the segment. Binding a parameter to a nested input field is the canonical description of the form.

@routine adds three rejections on top, because a routine IN parameter is resolved from the database catalog rather than by reflection:

Sample line. [author-error] field 'Doc.id': table 'doc' has a column named 'id' and also publishes node metadata, so 'id' is ambiguous. Add @nodeId to publish the global ID, or @field(name: "id") to expose the raw column.

Cause. The type is a node, so its id field is a candidate for the encoded global ID; the bound table also has a column of that name, so it is equally a candidate for that column’s value. Both readings are legitimate and they are different values on the wire, so the classifier refuses to pick one for you. The wording of the first clause varies with where the node identity came from: a table publishing \__NODE_TYPE_ID / \\__NODE_KEY_COLUMNS is named as such, and a type that declared @node explicitly is named as a node type over its table.

Next step. Write the reading you meant on the field. @nodeId publishes the encoded global ID; @field(name: "id") exposes the raw column, at the cost of that type no longer round-tripping through Query.node(id:). The @node reference covers both.