Troubleshooting Index
Start with the visible symptom and preserve the first complete error. Do not patch generated source merely because a compiler points at it.
By Failing Stage
| Stage or symptom | Start here |
|---|---|
| Model evaluation or generation report | Reading Markdown Reports, Troubleshoot First Run, and Diagnostics Catalog |
| Missing generated method | Troubleshoot First Run |
| Missing query purpose/comment or mutation audit | Diagnostics Catalog |
| Java generated-code debugging | Debugging Generated Code |
| Java SQL/logging behavior | Debugging and Logging |
| Java slow requests | Profiling |
| Java memory or connection pressure | OOM and Connection Leaks |
| Rust type inference | Type Inference Errors |
| Rust logging/tracing gaps | Observability and Tracing |
| Rust concurrency or deadlock | Concurrency and Deadlocks |
| Version/provider migration | Upgrade Guide and Migration Notes |
Minimum Diagnostic Record
Before escalating, collect:
- exact command and working directory;
- complete Markdown report or first error;
- model revision;
- generator/client and runtime versions;
- Java/Rust toolchain, framework, and provider versions;
- relevant generated signatures;
- whether clean regeneration reproduces the failure;
- smallest test or model that demonstrates it.
Fix Order
Prefer fixes in this order:
- Source model.
- Generator/client configuration and version alignment.
- Handwritten application or extension code.
- Runtime/provider configuration.
- Framework or environment.
Generated output is evidence to inspect, not the first patch surface.