Device can become permanently stuck: activation reports failure while the registration persists, and unbind cannot recover it

[u-ichi]

Summary

During first-time setup the app can leave a device registered on the xiaozhi backend while reporting activation as failed. Once in this state the user cannot recover: every retry fails, and unbinding from the device's own menu also fails. Three separate issues combine to make this a dead end.

Observed behavior

• StackChan World for Android v1.2.2 shows device activation and binding failed. please try again during setup.
• Unbinding from the device's settings menu shows Invalid response from server.
• The device itself shows no error at all. It joins the 2.4 GHz network, gets a DHCP lease, and performs TLS traffic.
• xiaozhi.me and api.xiaozhi.me are reachable from the phone. No firewall rules, no country restrictions, no DNS filtering, no client isolation.

Issue 1 — "already added" is detected by exact-matching a localized message

app/lib/util/XiaoZhi_util.dart, agentsDevicesActivate():

} else if (response.statusCode == 400) {
  ///Already added
  XiaozhiResponse xiaozhiResponse = XiaozhiResponse.fromJsonT(response.data);
  if (xiaozhiResponse.message == "该设备已经添加过，请不要重复添加") {
    return true;
  }
}
return false;

If the backend returns this message in a different language, with different punctuation, or with reworded text, the comparison fails and an already-registered device is treated as an activation failure — permanently, with no way for the user to tell why.

Suggestion: match on an error code rather than the human-readable message.

Issue 2 — activation can succeed while the app reports failure, leaving a partial registration

app/lib/view/popup/select_blue_device.dart, queryConfiguration():

final checkDevice = await XiaoZhiUtil.shared.serialNumberGetDevice(serialNumber);
if (checkDevice == null || checkDevice.agent_id == null) {
  //activatefail
  return false;
}

This GET runs immediately after the activation POST. If agent_id is not yet populated — backend not yet consistent, or no agent assigned — the app aborts. But the device is already registered on xiaozhi at this point. No toast is shown on this path, so the user gets no indication of what happened, and bindDevice() is never reached, so the M5Stack side stays unbound while the xiaozhi side is bound.

Suggestion: retry with a short backoff before giving up, and show a distinct message on this path.

Issue 3 — unbind failure surfaces as "Invalid response from server" with the reason discarded

firmware/main/hal/hal_account.cpp, unbindAccount():

cJSON *code = cJSON_GetObjectItem(root, "code");
if (code && cJSON_IsNumber(code) && code->valueint == 0) {
    onLog("Account unbound successfully");
} else {
    cJSON *msg = cJSON_GetObjectItem(root, "message");
    if (msg && cJSON_IsString(msg)) {
        onLog(std::string("Unbind failed: ") + msg->valuestring);
    } else {
        onLog("Invalid response from server");   // <- what users actually see
    }
}

Reaching that last branch means: HTTP 200 was returned, the body parsed as JSON, code != 0, and no message field was present.

In server/internal/controller/device/device_v2_unbind_device.go, the only error paths that return without a message are the two immediately following the xiaozhi call:

unbindResponse, err := xiaozhi.UnbindDevice(&req.Mac)
if err != nil {
    return nil, gerror.NewCode(gcode.CodeInternalError)      // no message
}
if !unbindResponse {
    g.Log().Error(ctx, "xiaozhi Unbind Device failed:")
    return nil, gerror.NewCode(gcode.CodeInternalError)      // no message
}

Every other error path in that function carries a message. This suggests users seeing Invalid response from server are hitting a failing xiaozhi-side unbind — but the reason is discarded, so neither the user nor support can tell.

Suggestion: attach a message to these two error returns.

Why these combine into a dead end

Issue 2 creates the partial registration. Issue 1 makes every subsequent retry fail. Issue 3 makes the escape hatch fail and hides the reason. The only remaining path is emailing support to clear the record on the backend, which is what several users have ended up doing — see #105 and the community thread "Stackchan unboxing and setup troubleshoot", where reports of "invalid response from the server" and "device configuration feature not found" appear repeatedly with no resolution.

Environment

• StackChan World for Android v1.2.2
• Google Pixel 10 Pro Fold, Android 17
• Router: UniFi Express 7. SSID is 2.4 GHz only, WPA2, PMF disabled, client isolation off, standard (non-hotspot) application, native network. No country restrictions or threat-management rules.
• Device firmware: v1.2.4

[herata]

Same dead end here, reached from a slightly different direction: I used "Unbind & Reset" (SETUP → Account) on firmware v1.4.4, and the device can no longer be bound. App shows failed, try again; the device stays on Ready to Configure ~ and never advances.

Additional data point: the device UUID is regenerated by the reset

This may explain why unbind/rebind can never recover the device.

xiaozhi-esp32/main/boards/common/board.cc:

Board::Board() {
    Settings settings("board", true);
    uuid_ = settings.GetString("uuid");
    if (uuid_.empty()) {
        uuid_ = GenerateUuid();          // random UUID v4
        settings.SetString("uuid", uuid_);
    }
    ESP_LOGI(TAG, "UUID=%s SKU=%s", uuid_.c_str(), BOARD_NAME);
}

"Unbind & Reset" ends in Hal::factoryReset() → nvs_flash_erase(), so the stored UUID is destroyed and a fresh random one is generated on the next boot. Confirmed from serial logs across the reset:

Before reset:  UUID=afaa2fa8-9495-4aa8-aa39-6db3fcf3267d SKU=m5stack-stack-chan
After  reset:  UUID=17a1ec49-23c2-42cf-b060-aa981882abf0 SKU=m5stack-stack-chan

If the backend keys its registration on this UUID, then a factory reset permanently orphans the record: the old UUID stays registered on the server, the new one is unknown, and there is no path back. That matches the "registration persists, unbind cannot recover it" behavior in the original report — and it would mean the device menu's own reset action is what creates the unrecoverable state.

Device side is healthy — the server simply never registers it

WifiStation: Got IP: 192.168.11.57
WifiBoard: Connected to WiFi: <2.4GHz SSID>
HttpClient: Established new connection to api.tenclass.net:443
Ota: Current is the latest version
Application: Activating... 1/10
...
Application: Activating... 10/10

Every activation attempt returns HTTP 202. Per ota.cc:

auto status_code = http->GetStatusCode();
if (status_code == 202) {
    return ESP_ERR_TIMEOUT;
}
if (status_code != 200) {
    ESP_LOGE(TAG, "Failed to activate, code: %d, body: %s", ...);
}

The Failed to activate, code: branch never fires, and the ~3 s retry spacing in my logs matches the ESP_ERR_TIMEOUT path exactly. So the server accepts each request but keeps the device in "waiting to be claimed" state indefinitely.

BLE binding stalls before the real exchange

[WifiConfigServer] app Connected
(26 config notifications sent, 56 characteristic writes received)

Traffic flows in both directions, but hal_ble.cpp logs get wifi config: <ssid> / <password> whenever setWifi arrives — and that line never appears. The app aborts after the handshake, before sending any configuration.

Workarounds tried, none worked

• Phone moved to the same 2.4 GHz SSID as the device (the fix reported in the community "unboxing and setup troubleshoot" thread)
• App storage cleared, app uninstalled and reinstalled
• Multiple bind retries, device power-cycled between attempts
• Wi-Fi reconfigured from scratch via the AP config portal at 192.168.4.1

Suggestion

Beyond the three issues in the original report: if the backend registration is keyed on the NVS-stored UUID, then factoryReset() should either preserve the board/uuid key, or derive the UUID deterministically from the MAC/eFuse instead of esp_fill_random(). Otherwise "Unbind & Reset" is a one-way door for any user who touches it.

Contacting support to clear the backend record, as suggested above.

[lidaye77]

The issue is very important, the developer should fix it immediately and publish one official version for flashing.
Who is responsible for this, fix it now !!!!!!