Skip to main content

Troubleshoot First Run

Start from the failing stage. Do not modify generated files merely because the compiler points at generated source.

Evaluation or Generation Prints a Markdown Report​

Applies to: cargo-teaql, cargo teaql, and TeaQL Maven evaluation or generation commands.

Diagnosis: Read the Markdown report from the beginning. Find the first model rule, file, or attribute identified by the report. Later compiler or generation errors may be consequences of that first problem.

Fix: Change the model or generator configuration, then evaluate again before regenerating.

Common cases:

SymptomSmallest credible fix
Empty KSML attributeRemove the attribute or give it a concrete valid value.
Depth exceededRemove one nested reference or use a string field where the model permits it.
Invalid relationship or typeCheck the KSML vocabulary and modeling rules before changing generated code.

Verification: Evaluation completes without the reported rule violation.

A Generated Method Does Not Exist​

Symptom: Java or Rust reports that an update, filter, selection, or relation method cannot be found.

Most likely cause: Application code guessed a method name, or the model was changed without regenerating the API used by the application.

Diagnosis: Open the generated entity or request source and search for the field or relationship. Use the exact method emitted by the current generator.

Fix: Regenerate if necessary, then change handwritten application code to use the actual generated contract. Do not add the guessed method manually to a generated file.

Verification: The application compiles and the generated method survives a second regeneration.

A Query Is Rejected for Missing Intent​

Symptom: Execution fails because query purpose or comment metadata is missing.

Fix: Finish the request with both business operation and intent before execution:

Q.orders()
    .comment("Query orders")
    .purpose("Render the order list")
    .executeForList(ctx);
Q::orders()
    .comment("Query orders")
    .purpose("Render the order list")
    .execute_for_list(&ctx)
    .await?;

Put filters, selections, ordering, and pagination before the terminal intent phase where the generated API requires that order.

A Save or Update Is Rejected for Missing Audit Intent​

Symptom: A mutation fails because audit metadata is missing.

Fix: Declare a concrete business action before persistence, using the exact method form generated for the target stack:

order.auditAs("Confirm customer order").save(ctx);
order.audit_as("Confirm customer order").save(&ctx).await?;

Avoid generic production messages such as save data; the audit description should let a reviewer understand why state changed.

The Generated Workspace Does Not Build​

Check these causes in order:

  1. Evaluation reported an earlier model failure.
  2. Generator and runtime dependency versions were manually mixed.
  3. The wrong build command or working directory is being used.
  4. Handwritten code still targets an older generated API.
  5. Generated files contain manual edits from before regeneration.

Use dependency versions and build instructions emitted by the current generator. If handwritten code fails, compare it with the current generated entity and request sources.

Generated Maven project has no project version​

If Maven reports 'version' is missing, inspect the source root model. A missing root version can generate an empty POM version. Add a concrete version to the model, evaluate, and regenerate. Do not edit the generated POM.

Dynamic target reports a missing .stg group file​

If generation reports a path such as generator/<target>/...stg, the selected target is advertised but its server-side template is incomplete. Preserve the Markdown report and the list-services output, then report the target and server version. Changing generated files cannot repair a template that was not delivered.

Generated dependency cannot be resolved​

If Maven cannot find the exact TeaQL artifact emitted by the generator, verify both the version and artifactId against official repository metadata. On 2026-07-13, java-lib-core emitted the nonexistent teaql-data-service-sqlite:1.525-RELEASE; the published artifact is teaql-sqlite:1.525-RELEASE. Preserve the generated POM and report the template defect rather than silently rewriting generated output.

Java entities cannot resolve internalSet or internalGet​

The current Java template generates overrides and super calls named internalSet and internalGet. teaql-core 1.525-RELEASE exposes the framework methods as __internalSet and __internalGet, including on the official main branch. If the compiler reports these missing methods, record the generator, runtime, and generated entity lines and report a template/runtime contract defect. Removing @Override or renaming methods in generated files is not a durable fix.

Rust console cannot find ../rust-lib-core/lib​

The current rust-app-console manifest uses a generated path dependency on ../rust-lib-core/lib. Generate rust-lib-core and rust-app-console into sibling output directories, then rerun cargo test from the application directory. Do not edit the generated manifest to point at the bundled lib/ copy.

Generated Rust sample data omits comment​

The cargo-teaql 2.0.8 output observed on 2026-07-13 contains two generated sample-data calls with purpose but no comment. The crate still compiles, but the calls do not meet this project's query-intent contract. Preserve the generated evidence and report the template defect. Handwritten queries must still end with comment → purpose → execute_for_xxx.

SQLite reports a root ID uniqueness conflict​

A generated runtime may seed the model's single domain-root candidate. Creating another root as though it were an ordinary repeatable entity can then collide with the seeded primary key. Inspect the model's root semantics and query the seeded root before creating audited child records. Do not work around the conflict by forcing IDs in generated source.

Escalation Evidence​

If these checks do not resolve the failure, collect:

  • client and runtime versions;
  • the exact command and working directory;
  • the complete Markdown report;
  • the smallest model that reproduces the failure;
  • the first build or runtime error;
  • whether the failure persists after clean regeneration;
  • the relevant generated method signatures.

This evidence distinguishes a model problem, generator defect, version mismatch, and application-code error without requiring generated-source patches.