Diagnostics Catalog
Status: Message-pattern catalog. No authoritative global numeric TeaQL error code registry has been identified in this repository.
The previous TQL-1001, TQL-2001, and TQL-3001 entries were removed because
their definitions could not be traced to a runtime, generator, or maintained
registry. Do not build automation around undocumented numeric codes.
| Metadata | Value |
|---|---|
| Authority | CLI/Maven Markdown reports, generated source contracts, and enforced project agent rules. |
| Scope | Modeling, generation, Java/Rust query execution, and mutation persistence. |
| Verified version | Generator Server 20260710.110004, teaql-java 1.525-RELEASE, and teaql-rs 4.1.1; exact messages remain version-sensitive. |
| Verification | Reproduce with the installed client/runtime and preserve the complete report. |
| Update trigger | New stable error registry, message change, validation-rule change, or intent-policy change. |
Diagnostic Families
| Searchable symptom | Likely cause | First action | Smallest fix |
|---|---|---|---|
Empty attribute | A KSML attribute has no concrete value. | Read the full Markdown report and locate the model element. | Delete the attribute or provide a valid concrete value. |
Depth exceeded | The model contains one nested reference too many for the supported boundary. | Inspect the reported relationship path. | Remove one nested reference or use a scalar/string field where appropriate. |
no method named update_... or Java cannot resolve an update method | Code guessed a generated method or uses stale generated output. | Open the generated entity source and inspect exact methods. | Regenerate if needed, then use the emitted method from handwritten code. |
Missing .purpose() or .comment() | A query reached execution without required intent metadata, or the terminal methods are reversed. | Inspect the final request chain before execution. | End the chain with .comment(...).purpose(...).executeForXxx(...) or the Rust equivalent, keeping purpose immediately before execution. |
Missing .audit_as() or .auditAs() | A mutation reached save/update without audit intent. | Inspect the persistence chain. | Add a concrete business audit description before save or update. |
| Generated workspace does not compile | Model failure, stale handwritten API use, or generator/runtime mismatch. | Start with the first evaluation/build error and generated dependency versions. | Fix the source model/configuration or align versions; do not patch generated source. |
TeaQL generation failed: input does not exist: <path> | The Maven input path resolved against the selected project base directory, or the file is absent. | Compare the reported absolute path with the model location and the POM selected by -f. | Pass the correct project-relative path or an absolute path; do not change generated output. |
'version' is missing in a generated Maven POM | The source root model omitted a concrete version. | Inspect the root model before inspecting generated source. | Add a non-empty model version, evaluate, and regenerate; do not edit the generated POM. |
No such group file: generator/<target>/...stg | A dynamic target is advertised but its server template is incomplete. | Preserve the Markdown report, target, and list-services server version. | Report the server-side target defect or use another verified target; generated-file edits cannot supply the missing template. |
Could not find artifact io.teaql:teaql-data-service-sqlite:1.525-RELEASE | The current Java template emits a nonexistent artifactId; the published module is io.teaql:teaql-sqlite:1.525-RELEASE. | Compare the generated POM with official TeaQL Maven metadata. | Report the generator template defect with both coordinates; do not patch committed generated output. |
cannot find symbol internalSet/internalGet plus invalid @Override | Generated Java entities target method names that are absent from teaql-core 1.525-RELEASE; the runtime exposes __internalSet/__internalGet. | Inspect the generated entity and javap io.teaql.core.BaseEntity for the resolved runtime. | Report the generator/runtime contract mismatch; do not rename generated methods manually. |
unable to update .../rust-lib-core/lib or missing Cargo.toml | rust-app-console was generated without its expected sibling rust-lib-core output. | Inspect the application manifest's path dependency. | Generate rust-lib-core and rust-app-console into sibling directories, then build again. Do not rewrite the generated manifest. |
Generated Rust sample_data.rs calls purpose without comment | The current generator template does not satisfy the project query-intent contract. | Confirm the call in generated output and record the client/runtime versions. | Report the template defect; do not patch generated output. Keep handwritten calls in comment → purpose → execution order. |
SQLite UNIQUE constraint failed: <root-table>.id while creating a root | The generated runtime already seeded the model's single domain-root candidate. | Inspect root semantics and query the initial root. | Reuse the seeded root for audited child creation; do not force a new ID or patch generated source. |
Startup rejects an unknown TEAQL_AUDIT..., TEAQL_SQL..., TEAQL_TOOL..., TEAQL_SINK..., or TEAQL_SCHEMA... variable | A generated-workspace variable is misspelled or an older *_LOG formatter variable was supplied to the strict teaql-tool-core parser path. | Read the startup suggestion and identify which of the two Rust configuration layers the application initializes. | Use the exact generated-workspace name, or configure the formatter layer only where it is explicitly initialized. |
Startup rejects a TEAQL_SQL_TABLES table or TEAQL_TOOL_FOCUS module | The filter contains a name outside the generated table catalog or supported tool-module list. | Compare the value with generated table names or the environment-variable reference. | Correct or remove the unknown comma-separated item; the parser intentionally fails rather than ignoring it. |
TEAQL_SCHEMA=_dryrun appears to perform schema work | The current generated runtime parses three modes but calls ensure_schema() in every branch. | Inspect generated runtime.rs and test against a disposable database. | Do not treat dry-run as a safety boundary until the generator/runtime implementation is fixed and verified. |
Markdown Report Workflow
For the verified report sections, severity meaning, exit behavior, and escalation record, see Reading Markdown Reports.
For Cargo evaluate, TeaQL Maven eval, and dynamic generation failures:
- Preserve the complete Markdown console report.
- Read from the first reported violation rather than the final stack line.
- Change the model, generator configuration, or handwritten extension.
- Evaluate again before regenerating.
- Confirm that the correction survives a clean regeneration.
Generation may instead fail in local path validation or return an HTTP error report for a server target/template problem. Use Reading Markdown Reports to identify the layer before choosing a fix.
Evidence to Collect for Unknown Failures
- Exact command and working directory.
- Client, generator, runtime, and toolchain versions.
- Complete Markdown report.
- First compiler or runtime error.
- Smallest model that reproduces the failure.
- Relevant generated signatures.
- Whether clean regeneration reproduces the issue.
Future Stable Error Registry
If TeaQL introduces stable error identifiers, each entry should include the code, exact message pattern, producer, version introduced, cause, diagnosis, fix, related command, and compatibility policy.
See Troubleshoot First Run for the guided recovery path.