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

Use the Board MPN value in --board. Letter case does not need to match, but punctuation and the rest of the identifier do. Also verify that a custom --config is pointing to the intended controller.

The controller version is not supported

The CLI checks controller compatibility before asking the controller to verify the API key. First run onmcu update and use the printed installer command if a newer CLI is available. If the installed CLI is current, check whether --config or ONMCU_CLI_CONFIG_PATH points to an incompatible custom 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.

In scripts and CI, where standard input is not a terminal, the CLI cancels automatically when the wait interval expires. It also cancels immediately on Ctrl+C instead of waiting for a confirmation that cannot be entered.

A configuration file is rejected

Use job_timeout_seconds, not the former timeout_seconds name. chunk_size must be between 1 and 10 MiB, and a remote controller URL must use HTTPS. Plain HTTP is accepted only for a controller running on localhost.

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.