Skip to main content

FAQ

This page is problem-first: it lists the symptom, then gives the shortest path to diagnose and fix it. Both CLI snippets and GUI actions are included.

Connection / portsโ€‹

Device / serial port not in the dropdownโ€‹

Symptom: the port selector is empty, or tyutool list-ports prints nothing.

  1. Unplug/replug, swap cable, swap port.
  2. Install the driver (CH340/CP2102/FT232).
  3. Re-check with the CLI:
tyutool list-ports
tyutool usb-port-survey   # raw USB metadata for cross-system debugging
  1. On macOS see macOS serial permission.
  2. On Linux, confirm you are in the dialout / tty group and log out and back in.
tip

Click refresh or reopen the app.

macOS serial permissionโ€‹

Symptom: the port is visible but you get a permission error.

sudo dseditgroup -o edit -a $USER -t user dialout

Then log out and back in. On newer macOS, allow it under Privacy & Security โ†’ Accessories. See the project README Troubleshooting.

Port busyโ€‹

Symptom: Permission denied / Device or resource busy.

Close other programs (Serial Debug, Arduino IDE, minicom, picocom); avoid running the GUI and CLI at the same time; you can turn on auto-release.

Flashingโ€‹

Flash fails / handshake failsโ€‹

Symptom: Handshake failed / Failed to sync.

Causes: wrong chip model (-d bk7231n / -d esp32 / -d t5ai); wrong baud (drop to 115200 first); device not in download mode (tyutool reset); wiring / power.

warning

First do a minimal repro: tyutool read -d <chip> -p <port> -l 0x1000.

Erase reports "unaligned"โ€‹

Symptom: unaligned / address not aligned / sector boundary.

Erase requires 4 KiB alignment:

# Correct: both start and length aligned to 4 KiB
tyutool erase -d bk7231n -s 0x0000 -l 0x200000
tyutool erase -d bk7231n -s 0x8000 -l 0x4000

# Wrong: 0x9000 is not a multiple of 4 KiB
tyutool erase -d bk7231n -s 0x9000 -l 0x1000   # โŒ reports unaligned
tip

Use the GUI's align action, or round down to a multiple of 0x1000.

Progress stallsโ€‹

Symptom: a stage sits at 0% for a long time, or retries repeatedly.

Drop the baud (921600 โ†’ 460800 โ†’ 115200); swap cable/power; turn on debug logs or CLI --verbose to debug/trace (location at CLI ยท global options); cancel gracefully with Ctrl+C.

Authorizationโ€‹

Authorization failsโ€‹

Symptom: authorize write failed / UUID/AuthKey invalid.

Credentials are one-device-once (used ones are spent); first do an auth-read tyutool authorize -p <port>; --uuid / --authkey must be passed together; specify -d for timing.

note

Credentials come from the Tuya developer platform and are bound to a chip/product.

Credential display issuesโ€‹

Symptom: you can't see the full value, or copying yields ****.

The GUI masks by default โ€” click Show or the copy button. With the CLI, auth-read:

tyutool authorize -p <port>
tyutool authorize -p <port> -d esp32   # read with chip-specific timing

Clear the clipboard promptly after copying.

Platformโ€‹

Linux blank window (WebKit compositing failure)โ€‹

export WEBKIT_DISABLE_COMPOSITING_MODE=1

Then launch the AppImage; you can add it to ~/.bashrc. See the project README.

Windows missing WebView2โ€‹

Install the Edge WebView2 Runtime Evergreen: download page โ†’ Evergreen Standalone Installer โ†’ run and restart.

note

For enterprise/offline, the Fixed Version offline package works too.

Logs & feedbackโ€‹

How to report a bug (with logs)โ€‹

  1. Export / open logs. GUI: Settings โ†’ Diagnostics โ†’ View logs โ†’ "Export logs and report a problem" = zip + pre-filled issue. CLI: read the log: line in the banner; --verbose prints to stderr.
  2. Use the issue template. Issues โ†’ New issue, pick Bug report.
  3. Fill in the key fields: Version / OS / Chip / Platform / baud / Steps / Expected vs actual.
  4. Attach the session log. Drag the zip into the issue, or for the CLI paste tyutool-<timestamp>.log.
warning

Logs may contain sensitive info (UUID/AuthKey) โ€” mask it first.