Troubleshooting

The CLI cannot find an API key

For interactive use, authenticate once:

onmcu login

For CI or another headless environment, both set the variable and opt into it:

export ONMCU_API_KEY='your-api-key'
onmcu list-boards --api-key-from-env

If Linux keyring access fails, confirm that a D-Bus session and Secret Service provider are running. See Authentication.

No matching board is found

Run:

onmcu list-boards

Pass the exact Board MPN value to --board. Also verify that a custom --config is pointing to the intended controller.

A Cargo or VS Code test reports unexpected arguments

Development tools append test filters such as --exact and --nocapture. Put --ignore-trailing-args before --file in the Cargo runner:

[target.thumbv7em-none-eabihf]
runner = [
  "onmcu", "run",
  "--board", "NUCLEO-H743ZI",
  "--ignore-trailing-args",
  "--file",
]

See Rust and defmt-test for the complete setup.

The job waits for a device

The matching hardware may already be in use. The default wait interval is 300 seconds. At the prompt:

• choose w to continue for another interval; or
• choose c to cancel the queued job.

Change the interval with --wait-timeout <SECONDS>. Use --timeout to limit how long the firmware may run.

The firmware runs until timeout after tests finish

A final log line does not stop a run. Call ARM SYS_EXIT_EXTENDED; otherwise the usual infinite loop keeps the job alive. See End a run with semihosting.

Logs are empty or unreadable

Confirm that:

• --logging rtt or --logging serial matches the firmware logger;
• the --baud value matches the UART configuration;
• a defmt ELF retains .defmt metadata and links defmt.x;
• the target and board memory maps match; and
• the firmware does not fault before logger initialization.

Read Firmware logging for known-good configurations.

The last log line is missing

Flush RTT or defmt before a semihosting exit. For serial output, wait for the UART and any bridge to drain before calling the exit function.

The CLI cannot determine final status

After the logs end, the CLI checks the job for about ten seconds. The stored status can lag behind the last log marker. If the job still has no final status, the CLI returns 13.

Retry with --verbose and keep the job ID from the output when reporting the issue:

onmcu --verbose run --board NUCLEO-H743ZI --file firmware.elf

Understand the failure code

See CLI exit codes to tell authentication, upload, board, queue, job, and status failures apart.