Troubleshooting

This page covers the errors most commonly reported by ameba-generate and by the generated project, in the order you are likely to hit them: option selection, SDK path resolution, building the generated project, then flashing it with the ameba-flash runner.

No Chip Selected (Headless Mode)

Error: No option selected for required group 'chip'.
Use -o <chip> where <chip> is one of: rtl8721f
Run `ameba-generate list-options` for the full list.

Cause: headless mode requires an explicit -o for every required option group, and chip is required.

Fix: add -o rtl8721f.

wifi Selected Without embassy

Error: option 'wifi' requires 'embassy' to also be selected.

Fix: select both, e.g. -o embassy -o wifi.

SDK Path Does Not Exist

Error: SDK path does not exist: /path/to/rust

Fix: confirm --sdk points at the Ameba Rust SDK checkout.

--sdk Does Not Point at a Rust SDK Checkout

Error: '/tmp' does not look like an Ameba Rust SDK checkout (missing ameba-hal/Cargo.toml).

This is checked up front so a wrong --sdk fails immediately, rather than surfacing much later as an unresolvable path dependency when cargo build runs inside the generated project.

Fix: pass the Rust SDK repository root — the directory containing ameba-hal/Cargo.toml.

Destination Already Exists

Error: destination 'my-app' already exists

Fix: remove or rename the existing directory, or choose a different project name.

cargo build Fails with unknown directive .thumb_func

This means cargo build ran from the wrong directory and picked up the host (x86) target instead of the ARM target configured in app/.cargo/config.toml.

$ cd my-app/app && cargo build                     # correct
$ cd my-app     && cargo build                      # wrong — reads the workspace root config, no ARM target
$ cargo build --manifest-path app/Cargo.toml         # wrong — does not read app/.cargo/config.toml

Fix: always run cargo build from inside app/.

cargo run: ameba-flash Not Found

error: could not execute process `ameba-flash flash --monitor <path>/target/thumbv8m.main-none-eabi/release/my-app` (never executed)

Cause: the runner configured in app/.cargo/config.toml is not installed, or ~/.cargo/bin is not on PATH.

Fix: install it from the Rust SDK checkout, and make sure ~/.cargo/bin is on PATH:

$ cargo install --path <rust-sdk>/ameba-flash --locked

cargo run: --port Not Provided

error: the following required arguments were not provided:
  --port <PORT>

Usage: ameba-flash flash --port <PORT> --monitor <ELF>

For more information, try '--help'.

Cause: ameba-flash needs a serial port, and neither --port nor the RTK_SERIAL_PORT environment variable was given.

Fix: pass the port after --, or set the environment variable:

$ cargo run --release -- --port /dev/ttyUSB0
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo run --release

cargo run: failed to open <port>

[run] flashing on /dev/ttyUSB99 ...
error: failed to open /dev/ttyUSB99: No such file or directory

The firmware is packaged first, so the [package] and [pack] lines are printed before this error.

Cause: the serial port does not exist, or is already held by another program such as a serial terminal.

Fix: check the port name (/dev/ttyUSB* on Linux, COM* on Windows), and close any other program that has it open.

cargo run: ROM handshake failed

[run] ROM handshake ...
[run] not in download mode, rebooting into UART burn mode ...
error: ROM handshake failed: SysProto; if the board's log UART is not at 1500000 baud, reset it into download mode manually

Cause: ameba-flash reboots a board running normal firmware into download mode by sending a command on its log UART. This does not work when the board’s firmware does not respond to it, or when the log UART is not at 1500000 baud.

Fix: put the board into download mode manually, then run cargo run again.