Troubleshooting

Widget shows stale data

The widget reads from a snapshot that vmuxPhone writes to a shared App Group. If vmuxPhone has not run recently, the snapshot is older than what the live session would show. Symptoms include a status chip that no longer matches reality and a missing alert glyph for a session that should be alerting.

Try these in order:

1. Open vmuxPhone for a few seconds, then close it. This forces a snapshot write and a widget reload.
2. Confirm vmuxPhone has Background App Refresh enabled in Settings → vmuxPhone → Background App Refresh. Without it, the snapshot only updates when you foreground the app.
3. Verify the host is reachable. The widget shows Working for an idle session even when the underlying host has gone offline; the Unavailable status only fires once vmuxPhone notices.
4. Pull the Home Screen down to refresh, then wait 30 seconds. iOS sometimes batches widget reloads.

A widget that has been on screen for many days without a refresh is usually budget-starved. iOS prefers to refresh widgets the user looks at; long-buried widgets get fewer slots. Move the widget to a more-visible page if currency matters.

Widget says "not connected" or shows a placeholder

A placeholder rendering means the widget has no window bound, or the window it was bound to no longer exists in the snapshot. Common causes:

• You added the widget but did not pick a window in Edit Widget. Open the editor and pick one.
• The window was deleted in vmuxPhone. The widget keeps its binding for one ID that no longer resolves. Re-bind to a current window.
• vmuxPhone has not been launched yet on this device after install or restore. Open vmuxPhone once so it can write the initial snapshot.
• The App Group entitlement is not in effect. This happens when you sideload a different vmuxPhone build than the one the widget extension was built against. Reinstall both from the same source.

Widget didn't appear in the widget gallery

If you long-press the Home Screen, tap +, and search for vmux but find nothing:

1. Confirm vmuxPhone is installed and has launched at least once. iOS does not register widgets from an app that has never run.
2. Reboot the iPhone. The widget gallery is cached; a reboot rebuilds it.
3. Update iOS. The Alert Monitor widget requires iOS 17 or later.
4. Check Settings → Screen Time → Content & Privacy Restrictions → Allowed Apps. If vmuxPhone is restricted there, its widgets are also hidden.
5. Reinstall vmuxPhone. The widget bundle is part of the app bundle, so a clean install re-registers it. Your saved hosts and windows are stored separately and are not lost by reinstalling.

If the gallery shows vmuxPhone's other widgets but not the Window widget, the bundle is registered but the Alert Monitor entry is filtered. This usually means iOS thinks the widget supports no families. Reinstalling vmuxPhone is the cleanest fix.

Edit Widget options can't be edited

If long-pressing the widget shows Edit Widget but the editor has no fields, or the Window picker shows nothing to choose:

• Empty picker. vmuxPhone has no saved windows yet. Open vmuxPhone, connect to a host, and let it produce a window. Return to the editor; the window list refreshes.
• Frozen editor. Tap outside the editor sheet, then long-press the widget again. The first iOS render of the editor occasionally fails on freshly installed extensions.
• Editor closes immediately. Reboot the iPhone. iOS caches widget extension metadata and a stale cache can reject configuration intents.
• Picker shows windows but won't save. Confirm vmuxPhone is signed in to iCloud with the same Apple ID as the iPhone itself. App Group entitlements depend on a valid sign-in.

Widget shows wrong theme colors

Widget theming is captured in the snapshot at the time vmuxPhone writes it. If you changed the theme of a window after the last snapshot, the widget keeps the old colors until the next refresh. Open vmuxPhone briefly to force a snapshot write.

If the theme never updates, the snapshot may be stuck on a default theme because the saved window is missing color metadata. Re-save the window in vmuxPhone — typically by re-applying the theme from the workspace settings.

Widget tap opens vmuxPhone but not the right window

Tapping the widget uses a deep link of the form vmux://window/<window-id>. If the link does not resolve to the expected window:

• The window ID has changed. This can happen if you exported and re-imported your hosts; re-bind the widget.
• vmuxPhone is mid-launch. Wait for it to finish launching and try once more.
• Another app has registered the vmux:// URL scheme. This is not standard but can happen with some development builds. Reinstall vmuxPhone to reclaim the scheme.

Alerts don't show on the widget

If a session is producing notifications but the widget never shows the bell glyph, the unread-alert flag is not being set in the snapshot. Common causes:

• Notifications are disabled for vmuxPhone in Settings → Notifications → vmuxPhone.
• The window's notification rules in vmuxPhone don't match the events you expect. See Notifications on iPhone for how rules are evaluated.
• You acknowledged the notification on another device or surface — the Mac, the Watch, or the Lock Screen — and the flag was cleared before the widget refreshed.

Open vmuxPhone, deliberately produce an alerting event in the session, and watch the widget. The bell glyph should appear on the next refresh slot.

Still stuck

• Alert Monitor widget reference — what each state means.
• Adding a widget — re-binding and re-adding instances.
• vmuxPhone troubleshooting — broader iPhone-side fixes that often unblock widgets too.
• vmuxPhone notifications — alert configuration that the widget mirrors.