Netsuke reports failures at the earliest stage that can identify them:
- YAML failures include locations when the parser provides them.
- Schema failures identify unknown or malformed fields.
- Jinja failures identify missing variables or invalid helpers.
- IR failures report missing rules, duplicate outputs, and cycles before Ninja starts.
- Ninja failures retain the subprocess exit status and output.
Human diagnostics include remediation hints where one is available. JSON mode exposes the same information as fields.
Terminal human-mode configuration-load events emitted by config_err_to_exit
include structured operation and error_category fields. operation is
diag_mode_resolution for the early diagnostic preference phase or
config_merge for the full configuration-merge phase; error_category is io,
validation, or parse. Paths and display text are never recorded. JSON mode
preserves the diagnostic document as the machine-readable failure output.
The --verbose flag enables diagnostic tracing, successful timing summaries,
and the final metrics snapshot described in
Diagnose configuration selection. It is
suppressed in JSON mode so stderr remains parseable.
Graph-generation tracing has a strict privacy boundary. At DEBUG and TRACE,
it does not emit the manifest AST, target or dependency names, recipe commands,
variable values, macro bodies, paths, or any other manifest content. The
retained telemetry is bounded: a trace span; fixed recipe_shell, outcome,
and error_category fields; the netsuke_runner_graph_generations_total
counter; and the netsuke_runner_graph_generation_duration_seconds histogram.
For manifest-specific diagnostics, use an explicit, access-controlled diagnostic workflow. There is no replacement log because manifest content may be sensitive and unbounded.