Diagnostics and logs

Capture an error

Human-readable errors are the default. For automation, request JSON:

aros --diagnostic-format json build --preset pc-x86_64 2>diagnostic.json

Errors go to stderr; intentional command output stays on stdout. The versioned envelope has a schema field of aros-tool-diagnostics-v1 and a diagnostics array. Inspect each diagnostic’s code, severity, stage, message, hint, and any optional source/context fields. Do not parse human wording.

A failed invocation exits nonzero. A diagnostic document can contain multiple findings, including warnings; the envelope is not a single error object.

When JSON diagnostics are selected, aros reserves stderr for that one document. A successful child process that writes to stderr is captured with the same 64 KiB bound as a failed child; it is never replayed as raw stderr. If a later step fails, the captured observation appears as a warning in the final diagnostic envelope alongside the error. If the invocation succeeds, it is available through an opted-in local log that accepts warn records. Normal child stdout remains command output, and the deliberately interactive aros board console retains its terminal streams.

Collect a local log

aros build --preset pc-x86_64 \
  --log-level debug --log-format jsonl --log-file ./aros-debug.jsonl

Supported levels are off, error, warn, info, debug, trace; formats are human and jsonl. Logging is off by default and requires an explicit local file.

Use both --log-level and --log-file in portable examples. Every shipped tool uses the same precedence: a file without an explicitly selected level uses info; an explicit --log-level off or matching AROS_*_LOG_LEVEL=off always disables logging and does not create the selected file. A command-line level overrides the environment; a non-off level without a file fails with an actionable diagnostic.

Logs are local observations and are not uploaded automatically. Standard records omit ambient timestamps and host identity, but explicit paths, board identifiers and bounded subprocess output can be present. Review the file before sharing it. A log file is not part of a deterministic artifact.

Identify the owning component

Prefix	Owner
AR	Frontend orchestration
AT	MetaMake transpiler
AV	Independent verifier
AC	Collector/linker driver
AF	Source fetcher
AH	AHI build runner
AG	Module generator
RM	ROM tool
AP	Internal release/installation boundary
AX	Experimental toolchain producer inspection

Codes are stable identifiers and are not reused for a different retired error. See the diagnostic model for the exact code definitions.

Captured child stdout/stderr are drained concurrently and bounded to 64 KiB per stream, with explicit truncation. Interactive console commands retain their terminal. Source Git operations have a 30-minute process-group deadline; source graph transpilation has a 10-minute deadline. Producer-plan Git queries instead use 1 MiB per stream, at most 10 seconds each within a 60-second Git inspection budget; they never replay untrusted Git stderr. Git failures preserve tool, exit_code, signal, timed_out and timeout_ms in the shared context when available. context.mode names the exact public command leaf (for example toolchain.plan or board.sd.write), so automation can retain command identity without parsing the message.

Producer inspection uses AX0101 for contracts, AX0102 for identities, AX0201 for Git prerequisites and AX0202 for input roots/resources. aros toolchain build also exposes AX0801 from the work-ownership boundary. Those failures retain any partially reserved work/output directories instead of deleting or automatically reusing them. Successful blocked plans contain findings on stdout; invalid inputs use the normal failure envelope on stderr. Do not interpret exit 0 as build permission.

Interpret source synchronization failures

Code	Boundary
AR0111	Input or ref
AR0112	Transport
AR0113	Repository lock
AR0114	Mutable repository state
AR0115	Candidate graph validation
AR0116	Publication and materialization

An AR0113 owner-record file persists by design. Its presence is not proof of an active or stale lock; the operating system owns the actual lock.

Publication and final-reporting diagnostics may carry context.commit_state. The value comes from the owner that crossed (or could not prove) its durable boundary; the frontend never infers it from a command name or from the presence of --apply:

Value	Meaning
rolled_back	The relevant publication boundary was not crossed, or its rollback was proven complete
committed	The owner proved a mutation succeeded before a later output or log operation failed
indeterminate	The owner could prove neither final state

An absent value after a final reporting failure means no owner reported a durable mutation; this includes ordinary previews. It is not a claim that a requested --apply would have succeeded.

Preserve the reported state and inspect it before retrying an indeterminate operation. Do not infer success or rollback from message wording.

Generated-file recovery

Module and ROM generation distinguish destination conflicts, unsafe targets, incomplete recovery, durability failures and uncertain commits. They preserve their AG/RM codes and provide a remediation hint for the specific failure. A completed predecessor recovery can appear as a publication.recovery log event.

Follow the troubleshooting guide for the next diagnostic step, and use the configuration reference for component-specific environment names.