[Bug]: Device setup cannot advance when no local platform prerequisites are installed

[Fuucodi0X]

[Bug]: Device setup cannot advance when no local platform prerequisites are installed

Summary

On Linux without a complete Android SDK, enabling the device hub leaves the first step of the "Set up devices" wizard unable to advance. The Continue button remains disabled, but this step does not explain which prerequisite is missing. The platform diagnostics appear in the next step, which the user cannot reach.

Installing the Android prerequisites and restarting T3 resolved the setup block on this machine. This report concerns the missing explanation and recovery path in the wizard, rather than automatic SDK installation.

Area

apps/web and apps/server, device onboarding.

Environment

• T3 Code desktop 0.0.44, distributed as t3code-bin 0.0.44-1.
• Omarchy, Arch Linux, x86_64, kernel 7.2.5-3-omarchy.
• Local device host; iOS is unavailable on Linux.
• Device hub 0.12.0 and agent-device 0.21.12 after installation.

Steps to reproduce

1. Launch T3 Code on Linux without a complete Android SDK visible to the desktop app.
2. Open the Device panel and start "Set up devices".
3. Enable the device hub in step 1.
4. Attempt to continue to the Simulators step.

Expected behavior

The current step should explain why setup cannot proceed and show actionable prerequisite diagnostics. For example, it should identify the missing Android SDK, Platform-Tools, Emulator, or current command-line tools. The user should be able to review those diagnostics without first having a ready device hub.

Actual behavior

Continue remains disabled and appears unresponsive. The first step gives no actionable explanation for the unsupported local host. The Simulators step contains platform availability information but is inaccessible through Continue.

Investigation

The installed server's DeviceService.readinessIfSupported returns without starting the hub when a local host has no available platforms:

if (
  summary.kind === "local" &&
  !summary.platforms.some((platform) => platform.available)
) return null;

DeviceSetup requires hostStatus === "ready" to enable Continue. The first step displays hostStatusDetail only when the status is failed. Together, these conditions leave the user blocked without the relevant platform prerequisite information.

Source references from the reviewed upstream revision:

• Continue readiness gate.
• Android prerequisite diagnostics.

The readiness early return above was verified in the installed 0.0.44 server bundle. This report does not claim a clean-checkout reproduction against upstream main.

Workaround and verification

Installed Java 21 and an Android SDK containing Platform-Tools, the Emulator, current command-line tools, the API 35 platform, and a Google APIs x86_64 system image. Configured the SDK environment for both the desktop login and the user service, then restarted T3.

The wizard became usable afterward. An API 35 AVD booted and the device hub detected it. The system image and AVD were installed to validate emulator operation; this report does not establish that they are necessary merely to advance the first wizard step.

Impact

Blocks first-time local Android device setup until the user identifies and installs prerequisites outside the wizard.

Suggested regression coverage

Verify the first wizard step with no available local platforms and with each missing Android prerequisite. Assert that the user can see the reason and recovery instructions while Continue is disabled.

Existing issues were searched for device setup, Continue, and Android SDK failures. No matching report was found.

[juliusmarminge]

Note

Grok responding on behalf of Julius.

Triage

Thanks for the careful write-up. I confirmed this on main (148e6deea0), and it's still there after 0.0.44, including today's 0.0.45 nightly. No open issue or PR covers it. The open PRs #11647, #11648, #12402, and #12429 change SDK lookup or hub startup, and the open PR #12712 only adjusts the message shown once a host is already ready. None of them explain a missing toolchain before the hub starts.

Continue is supposed to stay disabled after you enable the hub until something can actually run. On a local host with no available platform, readinessIfSupported returns without starting the hub and without setting a failed status (apps/server/src/device/DeviceService.ts). By then configure has already set hostStatus to idle and cleared hostStatusDetail, and list doesn't refresh when readiness is null, so the status just stays idle.

That leaves the wizard with nothing to show. Continue and Done require hostStatus === "ready" (apps/web/src/components/device/DeviceSetup.tsx), the later steps can't be opened directly, and the only detail line renders when the status is failed. The hub status line is also hidden unless a start is in progress or the hub is ready. The platform reasons already exist on the host summary (for example "Android SDK was not found…" from LocalDeviceHost.platformReason), and platformSetupStatus would display them, but that UI lives on the Simulators step. Settings → Integrations → Devices has the same gate, so it only shows platform status after hostStatus === "ready".

This falls short of what docs/user/devices.md describes, where the panel explains missing dependencies. Skipping the hub when no platform is available is still the right call. You don't need an Android system image or AVD to get past the first step. Availability depends on the SDK root, Platform-Tools, Emulator, and current command-line tools, and the "no virtual device" copy belongs on the next step, once the hub is ready.

What should happen: when the hub is enabled and the local host has no available platform, the first wizard step and Settings → Devices should show the existing iOS and Android reasons while Continue stays disabled. After you install a platform and refresh, the hub should start and Continue should unlock. A focused PR that links this issue and covers the no-platform wizard state is very welcome.