Troubleshooting
Find the symptom, then jump into the platform page (setup guides keep the detailed steps).
| Symptom | Where to look |
|---|---|
App won't start on macOS/iOS (appGroup is required) | Install → Apple hosts · Plugin config · Transport |
| Widget shows "No configuration" (macOS) | macOS setup → When it fails · Transport |
| Widget shows "No configuration" (iOS) | iOS setup → When it fails — also check Swift widgetId vs JS |
| Widget doesn't update (Apple) | iOS / macOS · reload budget in Updating data |
| Android widget empty or crashes | Android setup → When it fails — JS group must match package / meta-data |
| Desktop window not appearing / empty | Desktop setup → When it fails — capabilities windows labels |
Looking for widget.html in the app | You don't copy it for the default path — Desktop webview |
| Windows Widgets Board missing template | Windows setup — path is src-tauri/windows-widget/, set TAURI_WIDGETS_DATA |
| Linux pin / layer-shell issues | Linux setup → When it fails · Linux harness |
| Empty widget after wrong Apple transport | Transport — init fails loud; check plugins.widgets.transport |
| Capability degraded / unsupported | Core vs extended · getWidgetDiagnostics in JS API |
Contributor tooling (goldens, harnesses): Contributing.