Troubleshooting

Start with the first reported code and the exact source/preset used by the failed command. Preserve outputs and evidence before retrying with cleanup.

Capture a machine-readable failure

Re-run the failing command with JSON diagnostics:

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

The process writes exactly one aros-tool-diagnostics-v1 document on failure and exits non-zero. To collect local execution events as well:

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

Logs are never uploaded automatically. Review them before sharing because local paths and board identifiers may be present.

Common boundaries

Code family	Boundary	First check
AR0101	repository discovery	Enter the intended checkout or use a global command such as source init
AR0111–AR0116	source lifecycle	Inspect input, transport, lock, state, validation or publication as reported
AR02xx	checkout configuration	Validate aros-targets.toml and the requested preset
AR03xx / AR04xx	helper or toolchain resolution	Run build-tools check or toolchain verify
AR05xx	network transfer	Check URL, proxy and offline policy; do not disable checksums
AR06xx	configure/build	Inspect the named build step and its captured output
AR0701	PC boot check	Read the retained serial/exception evidence; verify QEMU and PC boot inputs
AR08xx	board/media safety	Re-run scan or dry-run; never substitute a raw device path
AT…	transpiler	Update the transpiler when a capability fingerprint changed
AG…	module generation	Treat partial SDK output as invalid and rebuild after fixing the reported path
RM…	ROM/package tool	Fix the input; the previous destination remains intact
AV…	independent verifier	Inspect deterministic reports in the named work directory
AX…	native toolchain producer	Preserve the work/output roots and inspect the lifecycle receipt named by the diagnostic

Checkout not found

Commands classified as checkout-required search upward for the canonical AROS source layout: configure, Makefile.in, and the arch/, compiler/ and rom/ directories. aros-targets.toml is optional: a pristine checkout uses the target contract embedded in aros-tools, while an existing file is an authoritative override and must validate completely. The CLI does not infer a sibling directory. Use aros source init PATH, enter an existing AROS checkout, or choose a command that is explicitly global.

Tools missing or versions mixed

Run aros build-tools check. It checks all six required CMake helpers in one directory. Confirm that PATH points at the intended suite, or inspect an explicit AROS_BUILD_TOOLS_DIR. An invalid explicit directory is not silently replaced by a PATH candidate. Rebuild the workspace as one unit for a source installation.

Preset exists but no compiler is available

A built-in target profile is not a toolchain lock. Check aros toolchain list inside the selected checkout. Use its qualified lock or explicitly verify a local AROS-built prefix. Managed host LLVM also requires a declared digest; the built-in asset names alone do not meet that requirement.

Offline or checksum failure

--offline means no network request may occur. Install the exact artifact once online or populate the verified cache through the documented release path. Never copy an unmeasured archive into the cache.

--require-fetch-checksums intentionally rejects an AROS recipe without a declared SHA-256. Add evidence to the source recipe or update the transpiler; do not invent a hash for a moving URL.

Native producer preflight or cache rejected

AX0102 means one of the explicit source, producer, tools, recipe, or executor identities does not agree. Recreate the recipe from clean, exact checkouts; do not substitute a branch name or edit a digest to make the plan continue.

AX0401 reports an unusable controlled external environment. For a local build, first verify the lock-selected source cache, then recreate the lock-matched Cargo vendor cache from the selected aros-tools checkout as described in the native producer workflow. Do not add a package with pip, reuse ambient Python modules, or let an offline producer run fetch a missing Cargo crate.

AX0501–AX0503 identify configure, compiler/runtime, or collector stages. The command retains the owned work and output roots and writes a receipt after each completed stage. Preserve those receipts and the captured logs when reporting a fault. A retained directory is evidence, not permission to adopt or resume it automatically.

Sync refused

aros source sync requires a clean attached branch, clean recursive submodules, the expected canonical upstream URL and a fast-forward relationship. Commit or stash work deliberately, correct the remote, or reconcile divergent history manually. A repository-wide lock reports AR0113; wait for the descriptor owner to exit. The owner-record file is persistent by design, is reused after crashes, and must not be removed. The command also rejects replacement refs, grafts, repository-local attributes, filters, sparse-checkout controls, URL rewrites and credential overrides because they could make validation and publication observe different source trees.

The command uses compare-and-swap publication and never creates a merge commit, runs reset --hard, or overwrites concurrent user changes. If both a post-CAS step and safe rollback fail, preserve the checkout and inspect the reported branch, index and submodules before retrying. In JSON diagnostics, context.commit_state: "indeterminate" means the CLI deliberately made no stronger claim; do not infer state from the prose message.

Package or release installation

Verify the release checksum, signature/attestation and target triple. Keep all eight binaries on one version. Package-manager repositories are supported only after the release-status page marks their public verification complete.

Board label does not select the hardware

board init --profile NAME --model MODEL uses NAME only as a registry label. Select the actual model explicitly; the template selects the matching backend and default transport. Use --transport uboot-usb-ecm only for Pi 4. Pi 3 and Pi 5 reject USB-ECM, and Milk-V Titan rejects Pi TFTP transports. See the board workflow for the supported matrix.

If the documented checks do not explain a failure, open a GitHub issue with the tool version, host target, stable diagnostic document and minimal reproduction. Use the private process in SECURITY.md for security-sensitive details.