Skip to content
TroubleshootingSource reviewed

MicroDuck troubleshooting: updates, pairing and policies

On the official MicroDuck, daemon 0.20.1 supersedes 0.20.0 and removes system.openWifiSsh. A refused Wi-Fi SSH connection alone does not mean the update failed.

Official MicroDuck upgrade and recovery

  1. Before updating, record the installed version and health output; retain the working image and configuration.
  2. Choose the symptom below and read the checks for that exact release. Connection, service, sensor feedback and policy compatibility are separate conditions.
  3. After the change, read back the version and settings, then check health and policy selection. Use the recovery procedure for the same image and hardware if a check fails.

MicroDuck 0.20.1: check access before recovery

Official robot only: daemon-v0.20.1, released 2026-11-12, revision 7fba12ed, API 55. We checked the release, fixed source and published archive; no robot was booted or updated for this guide. HD1910 replicas and Open Duck Mini use different software.

Confirm the installed version

From an already authorized laptop connection, run the read-only version and update-status commands below. Record release, revision, API and the update outcome. Reconnect after an update restarts BLE before diagnosing a dropped session.

Keep Setup Code on your own device

Use the robot’s own QR or code with a compatible app. For laptop duckctl, setup-code add reads the code from standard input and stores it locally. A provisioned robot refuses the legacy PIN. A stale key can cause a silent failed handshake; check robot identity and client version before resetting pairings.

Wi-Fi SSH refusal has a separate cause

0.20.0 could open Wi-Fi SSH over BLE using the Setup Code; SSH then accepted a shared operator password. 0.20.1 withdraws that method and duckctl ssh-wifi. Wi-Fi SSH requires a deliberate local USB-C action with the robot open, or a development image. Check the upstream access instructions rather than retrying the removed command. A v54 client requesting system.openWifiSsh is explicitly refused by API 55.

duckctl --name <robot-name> version
duckctl --name <robot-name> update status

In this stable tag, the policy installer has a v9 minimum, not a v9 ceiling: newer official sets and custom sets are preserved under its source rules. HF v10 and API 56 on later main are separate evidence, not features established by the 0.20.1 tag.

For help, record the access path (BLE / USB-C / Wi-Fi SSH), daemon and client versions, and the first redacted error. Keep Setup Code, QR keys, PIN and network credentials private. The earlier 0.19.0 pairing and camera checks remain below.

Editorial checklist for official MicroDuck 0.20.1: installed version, local Setup Code and the separate Wi-Fi SSH access decision.
Original editorial diagram from the fixed 0.20.1 source; not a photo, simulation result or hardware test.

MicroDuck 0.19.0 pairing and camera checks

This covers the official daemon 0.19.0 tag released on 2026-11-10. It applies to the official robot. Source and release files were checked. The maintainer’s iOS QR, secure BLE and camera check used a face-board-v1 beta unit.

Setup Code: scan the robot’s QR

Scan the QR for this robot in an app that supports Setup Code. The daemon takes the credential from ID EEPROM or the installed development key. Changing the display name leaves the original duck-xxxx identity used by the code in place.

No credential: label PIN

If the robot has no valid credential, btd uses its PIN path and duck-gateway has no key to serve. If a label is present but the code fails, confirm that it belongs to this robot and check the app version before changing settings.

Paired: check Wi-Fi and video

If secure BLE connects and video is missing, check the phone’s local-network access and the robot’s Wi-Fi first. On iOS, retry video in the app after allowing local-network access. On a provisioned robot the app authenticates to duck-gateway, which forwards to mediad on loopback.

The daemon pins official policies to v9. For VelStand, v9 ships the v7 checkpoint. The newer yaw-remap experiment in microduck_rl has a separate scope.

Before changing pairings or recovery settings, record the installed daemon, phone app version and first error. Use the read-only status command if you already have authorized access. Share the failing stage and a redacted error without the QR, PIN, setup key or Wi-Fi credentials.

robotctl update status

Connect a MicroDuck: Find It, Join Wi-Fi, Open the Console

On an official MicroDuck, use duckctl from a laptop to distinguish Bluetooth discovery, missing Wi-Fi address and console signalling before changing settings.

MicroDuck 0.18.3: Telemetry Controls & Reconnection Checks

Check MicroDuck 0.18.3’s default-on usage telemetry, opt-out readback and SSH address cache, plus 0.18.2 gamepad recovery, before updating a compatible robot.

MicroDuck Policies: Update v8, Inspect Overrides & Reset

Check the official v8 velstand policy, update the separate policy set, identify persistent walk overrides, and reset one slot safely.

Start at the first failing stage.

Use the table matching your environment. A browser loading problem, a missing Python dependency and an ONNX shape mismatch happen at different stages. Keep the original error before changing versions; otherwise you may lose the clue that identifies the failing layer.

Browser simulator problems.

Browser symptoms and the next check
SymptomTry thisWhat to record
Stuck on loadingOpen the direct simulator. Try the official boot diagnostic view ↗. Wait for its asset or policy step to finish.Browser version, the last loading step and any SYSTEM HALTED error. A transient network failure is not evidence that your GPU cannot train.
The robot ignores the arrowsEnter or resume the scene, click it to give it focus, then hold an arrow. Try the direct page if the wrapper is capturing keys.Whether the welcome overlay closed, whether the page scrolled, and whether the speed readout changed.
R sits instead of rollingUse the current browser key map. R now controls sit/stand in feet mode.The tutorial URL and simulator revision. Do not substitute shortcuts from the local Python viewer.
Kicks fail after switching modeReturn to Feet mode. Kicks and ground pick are legs-only actions; the first Rollers switch also has extra loading.Selected mode and whether its assets finished loading.

These checks combine our desktop entry/walking/reset check with the Simulator README: modes, loading and controls ↗ and Browser keyboard implementation ↗. No browser benchmark or mobile compatibility claim is implied.

Installation and CUDA problems.

Dependency and GPU symptoms
SymptomNext check
Python version rejectedRun uv run python --version from the checkout. This revision requires 3.12; use the pinned setup steps.
GPU exists, but CUDA is False or GPU count is 0Run the Python/CUDA probe from the same environment as training. Record PyTorch’s version and CUDA build, OS and architecture. On Linux ARM, inspect the project’s selected wheel source before changing drivers.
ARM dependency download times outThe official quick start suggests a longer uv HTTP timeout for the first large CUDA-wheel download. Try the one-command setting below. It only addresses download timeouts.
Jetson Thor: missing NVPL or cuDSS libraryRead issue #38 with your exact JetPack, driver and architecture. It documents a Thor-specific package problem; a GB10 package recipe is not automatically a Jetson recipe. The report was still open at review.
An unrelated train command runs, or train is missingUse uv run train inside the synced checkout. The project intentionally owns this entry point; its dependency file documents a previous executable collision. Re-sync the matching revision before altering your system PATH.
CUDA out of memoryRecord the allocation error, GPU memory and environment count. Close only your own unused GPU jobs, then retry the same task with fewer environments. This is a diagnostic reduction, not a guaranteed cure for every allocation failure.
Retry a timed-out dependency download
UV_HTTP_TIMEOUT=600 uv sync --locked --python 3.12

Run that one-line assignment in a POSIX shell such as bash or zsh. The underlying constraints and executable collision are documented in Python, dependency pins and ARM package sources ↗; GPU discovery is described by PyTorch: checking CUDA availability ↗. Jetson Thor report #38 (community report, open at review) ↗ is a user report, not a fix tested by this site.

Export and replay problems.

Policy symptoms and matching checks
SymptomNext check
ONNX expects 61 inputs but receives an older layoutFor the reviewed current policy contract, use --new-cmd-obs in the local viewer. Leave it off for legacy 51-input policies. Confirm the actual input shape before choosing.
A .pt file will not load as ONNXUse the official checkpoint exporter. The file types serve different purposes; renaming a checkpoint does not convert it.
play looks plausible, but exported replay behaves badlyCheck that the official exporter included observation normalization. Then compare task, checkpoint, robot model, action scale and command layout. This is an investigation order, not a diagnosis of your specific policy.
A remote job continues after Ctrl-COpen the saved job URL, inspect its status and explicitly cancel if appropriate. Interrupting the log stream does not stop the job.

Inspect Local playback flags and keyboard controls ↗ and Official ONNX exporter and observation normalization ↗ for the layout and normalization behavior. The cloud log behavior is documented in MicroDuck cloud job submission guide ↗; cancellation is covered in Hugging Face: managing and cancelling jobs ↗.

On an official robot, separate a Bluetooth pad problem from a control-source change.

This section is a source-reviewed diagnostic path for the official daemon 0.17.2, released October 13; the site reviewed it October 14 and did not pair a pad or operate a robot. It does not describe a replica or the browser simulator. The official Bluetooth pairing page and history script already existed before 0.17.2. 0.17.2 release ↗ pairing and link guide ↗.

Save the read-only baseline below before attempting a new bond, a service restart or a controller setting. configure --list lists overrides, so no netpad.enabled line usually means the default false, not a failed query. The two output lines from systemctl are ordered padd, then netpadd. This is a source-selection check, not another UDP setup tutorial; the 0.17.2 release guide explains the new UDP timing. official commands ↗ source selection ↗.

Read-only pad baseline on the robot
robotctl version
robotctl configure --list
systemctl is-active padd netpadd
robotctl pad status
robotctl pad bindings
robotctl logs padd -n 100
robotctl logs bluetooth -n 100
Official-robot pad symptoms and the next evidence to read
What you seeWhat it can meanNext step
padd inactive; netpadd activeUDP is the selected source, so a Bluetooth pad cannot drive during that configuration.Read the configured override and current source-switch guide; do not re-pair a Bluetooth pad to fix a deliberate UDP choice.
padd active; no pad connectedThe driver is running, but there is no current Bluetooth input. A pad shown as paired but NOT trusted may work now yet fail to reconnect after a reboot.Record pad status and padd/bluetooth logs. If trust is the identified fault, follow the original controller-specific pairing steps; do not erase every bond first.
Pad connected; padd inactiveThe radio bond and the driver can fail separately. A connected icon alone does not prove that the robot receives control.Compare both service states and the padd journal. If neither source starts, report its first service error before changing settings.
Pad connected and driver active; one button does nothingA binding or mode may explain it. Since 0.16.2, X/Y/LB/RB have no default action; 0.17.2 can also override stick axes, gains and limits.Read pad bindings, configure --list and the current mode. An empty override list does not print all effective defaults.
Pad connected and driver active; input appears to freeze while drivingA radio stall is different from a disconnect. padd can resend the last stick value at 50 Hz, so a fresh downstream intent is not proof of fresh pad reports.Check the padd journal first. The official robotctl monitor p panel shows raw evdev report gaps, but interpreting it while moving sticks requires a supported, controlled hardware test.

The original pairing guide ↗ distinguishes a connected controller from an active driver, and its Pro Controller example shows why manual connect-before-pair can leave no input device. Do not change BlueZ Privacy by guesswork: the official document records different failure reasons requiring different settings. Its history script ↗ reads existing padd and kernel journal records without a live pad; a 0x08 supervision timeout points to range or interference, while 0x13/0x16 indicates the pad was switched off. Missing history does not prove a reliable link, and a resting pad sends no reports. Never call a live stick test read-only merely because the monitor command only reads data.

When sharing a question, include the daemon version, source states in order, the two pad status lines, actual button bindings and a short timestamped log excerpt. Remove controller addresses, local IPs, serials and account details. State whether the observation came from an official physical robot; a browser simulation cannot test its Bluetooth radio. The 0.17.2 UDP stale_ms stop and timeout_ms session loss apply to netpadd, not to this Bluetooth pad diagnosis. UDP state machine ↗ stop and loss handling ↗.

Send a report someone can act on.

Replace the fields below with what you observed. Include a short, relevant error excerpt; remove tokens and personal paths before sharing. “What worked last” is often more useful than a screenshot of the final exception alone.

Troubleshooting report template
Goal:
Failing stage (browser / setup / CUDA / training / export / replay):
Page URL or repository + full commit:
OS and architecture:
Browser OR Python / uv / PyTorch / CUDA versions:
GPU and driver, if relevant:
Task ID / policy source / input shape:
Exact command or sequence of actions:
Expected behavior:
Actual behavior:
First error (short excerpt, secrets removed):
Last successful step:
One change tried and its result:

Start a related discussion →. For a suspected upstream bug, include the same minimal reproduction at the original project’s available support channel.

Continue with your result.

CONTINUE THE CONVERSATION

What would you like to understand next?

Keep the source, your environment and your observations together.

Before you continue

Why is Wi-Fi SSH refused after MicroDuck 0.20.1?

Check version and update status over an already authorized connection first. Official 0.20.1/API 55 removes system.openWifiSsh and duckctl ssh-wifi; Wi-Fi SSH needs the local USB-C or development-image route documented upstream. A refusal alone is not proof of an update failure. HD1910 replicas and Open Duck Mini are outside this scope.

Applies to: Pollen Robotics MicroDuck. Keep the model, image, software and driver versions together. The dated sections below retain their original verification limits.

Source checked:

Sources and review (21)
  1. huggingface.co/spaces/pollen-robotics/microduck-simulator/blob/e81974b932c7ca1819843b7bb3dcd42e2993e98e/README.md
  2. huggingface.co/spaces/pollen-robotics/microduck-simulator/blob/e81974b932c7ca1819843b7bb3dcd42e2993e98e/app/src/game/controls/keyboard.js
  3. github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/pyproject.toml
  4. docs.pytorch.org/docs/stable/generated/torch.cuda.is_available.html
  5. github.com/pollen-robotics/microduck_rl/issues/38
  6. github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/scripts/infer_policy.py
  7. github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/src/mjlab_microduck/export.py
  8. github.com/pollen-robotics/microduck_rl/blob/2b25a48b08f1f17bc38c90bb03144c81fbd9ed07/scripts/hf/README.md
  9. huggingface.co/docs/hub/jobs-manage
  10. github.com/pollen-robotics/microduck/releases/tag/daemon-v0.17.2
  11. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/docs/robot/pair-a-gamepad.md
  12. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/docs/robot/cheatsheet.md
  13. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/scripts/pad-link-test.sh
  14. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/docs/robot/udp-pad.md
  15. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/netpadd/src/receiver.rs
  16. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/netpadd/src/main.rs
  17. github.com/pollen-robotics/microduck/blob/35b71a2a4499eb22216b3417e19e97db602561d4/robotd-params/src/pad_axes.rs
  18. github.com/pollen-robotics/microduck/releases/tag/daemon-v0.20.1
  19. github.com/pollen-robotics/microduck/pull/574
  20. github.com/pollen-robotics/microduck/blob/7fba12ed048d0d3a1c306ba8a2787a1a407b9974/docs/robot/duckctl.md
  21. github.com/pollen-robotics/microduck/blob/7fba12ed048d0d3a1c306ba8a2787a1a407b9974/scripts/seed-policies.sh

Next useful guides

Connect a MicroDuck: Find It, Join Wi-Fi, Open the Console

On an official MicroDuck, use duckctl from a laptop to distinguish Bluetooth discovery, missing Wi-Fi address and console signalling before changing settings.

MicroDuck 0.18.3: Telemetry Controls & Reconnection Checks

Check MicroDuck 0.18.3’s default-on usage telemetry, opt-out readback and SSH address cache, plus 0.18.2 gamepad recovery, before updating a compatible robot.

MicroDuck Policies: Update v8, Inspect Overrides & Reset

Check the official v8 velstand policy, update the separate policy set, identify persistent walk overrides, and reset one slot safely.