Troubleshooting & FAQ

Something not working? Start here. Most issues are quick fixes.

Can’t Connect to Home Assistant

Check the basics first:

Your URL should match exactly what you type in your browser — including http:// vs https:// and the port number
Your iPhone needs to be on the same Wi-Fi as your HA server for the local URL
Try the IP address directly if homeassistant.local doesn’t work (e.g., http://192.168.1.100:8123)
Using Nabu Casa? Enter your Nabu Casa URL as the Remote URL. Make sure your subscription is active and remote UI is enabled.

SSL errors? When you test a URL, the app detects an untrusted certificate and tells you directly (“HTTPS certificate is not trusted on this device”). Self-signed certificates need to be trusted on your iPhone first: Settings > General > About > Certificate Trust Settings — or just use the local http:// address.

“Auth failed” on watch? Your credentials are invalid or expired. Open the iPhone app and sign in again from Settings → Home Assistant, or replace your long-lived access token.

Watch Not Connecting Directly

The watch needs to be on the same Wi-Fi as HA (or use Nabu Casa). Check Settings → Watch Behavior → Connection → Server Mode is set to Auto or Local. Some networks isolate devices on different VLANs — make sure the watch can actually reach your HA server.

If a direct connection isn’t available, the watch falls back to iPhone relay automatically.

Connection Keeps Dropping

Weak Wi-Fi is the usual culprit. Move closer to your router or add a mesh node. If you see frequent reconnects, bump up the Timeout under Settings → Watch Behavior → Connection (try 35s or 45s).

The connection dot on the watch tells you what’s happening: green = healthy local connection, orange = healthy remote connection, yellow = connecting or degraded, red = offline or error.

Tiles Not Updating or Showing “Unavailable”

Not updating? Check the connection dot is green. Try closing and reopening the watch app. Make sure the entity still exists in HA.

“Unavailable”? That’s Home Assistant saying the physical device is offline or the integration needs reloading. Fix it on the HA side.

Layout Not Syncing

Open the iPhone app — syncing happens when it’s active, and the watch usually catches up on its own within a few seconds of the phone being open. Make sure your watch and phone are connected (check the Watch app). If it’s still behind, toggling any setting forces a fresh sync. Reinstalling the watch app is rarely necessary.

Watch App Feels Slow

Split big pages — Pages with 20+ tiles are heavy. Use multiple smaller pages.
Lower camera refresh — Camera tiles use the most resources.
Ease up on animations — Lots of continuous animations on one page adds up.
Restart the app — Long sessions can accumulate memory pressure.

Can’t Find an Entity

Make sure it exists and isn’t hidden or disabled in Home Assistant. Pull down to refresh the entity list. Try browsing by domain instead of searching.

Gestures Not Working

Motion gestures — Check sensitivity isn’t Off. Start with High to confirm it works, then lower it. Make deliberate, quick wrist twists. Only works when the app is active.

Hand gestures — Requires Series 9, Ultra 2, or newer. Make sure the action isn’t set to Disabled.

Complications Showing Stale Data

Complications only auto-refresh if you turn it on — the default is manual refresh only (tap to update). Set an interval per complication (5, 15, 30, or 60 minutes) in the Widgets editor. watchOS limits how often complications can actually refresh — that’s an Apple restriction, not us.

Control Center widgets not showing? Requires watchOS 26 and later. Swipe up → scroll down → Edit to add them.

Notification Fails with “No Registered Push Token”

If Home Assistant shows an error like Failed to perform the action script/watch_nnnnn. No registered push token for watch ..., Home Assistant knows about the watch, but that watch has not checked in for notifications yet.

This usually clears on its own. Open the iPhone app and let it sync — the watch registers in the background once the phone is active. Opening Wrist Assistant on the Apple Watch and letting it connect once does the same.

If it still fails:

Check on the watch that notifications for Wrist Assistant are enabled
Reopen Wrist Assistant on the watch and wait for it to connect
Retry the Home Assistant notification or blueprint run
Re-pairing or reinstalling the watch app is a last resort — recovery is almost always automatic once the iPhone app is open

If your remote Home Assistant sits behind Cloudflare Access or mutual TLS, browser sign-in dead-ends at a 403 — or setup tells you the server requires a client certificate. Safari’s sandbox can’t present a certificate you’ve imported into the app, so the normal sign-in flow can’t get through.

The fix is to import your certificate, then let the app handle sign-in itself:

In Settings → Home Assistant, expand Certificate (mTLS) and import your .p12 or .pfx file (you’ll be asked for its password if it has one).
Sign in again. With a certificate installed, browser sign-in opens inside the app so it can present your certificate.

If you’d rather not use browser sign-in, you can instead sign in once on local Wi-Fi (where mTLS usually isn’t enforced) or paste a Long-Lived Access Token directly into the Access Token field.

Notification Arrives but Won’t Expand

If a notification shows up as a plain banner that won’t expand to reveal its buttons or camera snapshot, restart your iPhone. After an app update or restoring from a backup, iOS sometimes fails to load the notification’s rich view until the phone is restarted.

Update Banners

The iPhone app shows a banner when your integration or app versions are out of step. There are three:

“HA Integration Update Available” (blue, informational) — A newer integration release exists but your current one still works. Tap to update via HACS through the in-app update sheet. Safe to ignore until you’re ready.
“Update Wrist Assistant integration” (orange, urgent) — Your installed integration is too old for this version of the app, and your watch will not work until you update it. If the integration is HACS-managed, tap the banner to update via HACS; for manual installs, update by re-copying custom_components/wrist_assistant/.
“Update Wrist Assistant” (app out of date) — Your integration is newer than the app. Tap to open the App Store and update the app.

For HACS-managed installs, tapping a banner opens an in-app update sheet pre-filled with the right version — no need to dig through HACS yourself. Restart Home Assistant after the update completes.

My Watch Shows “A Version Behind” / a Red Version Badge

In Setup Check, the watch-app version row sitting on Watch app update pending (with a red version badge in the section header) is advisory, not an error. watchOS installs the matching watch-app build on its own schedule — usually within a few hours — and the app cannot force the install itself.

To hurry it along:

Put your Apple Watch on its charger, near your iPhone, both on Wi-Fi. watchOS installs queued app updates while the watch charges — this is what usually triggers it.
Or force it now: open the Watch app on your iPhone, find Wrist Assistant, and toggle Show App on Apple Watch off, then back on. That reinstalls the current version right away.

The same advice lives in Setup Check, where the row’s Update it now disclosure spells out these two levers.

Watch Stuck on “Set Up on iPhone”

A freshly installed or freshly paired watch can sit on the Set Up on iPhone screen for a moment while it waits for your phone to hand over the layout.

Open the iPhone app and keep it open for a few seconds. The watch self-heals automatically once the phone is active — it keeps asking your phone for the configuration in the background until it lands, no force-quit needed.

Only if it persists after that, force-close the watch app and reopen it.

”Setup Failed” on the Watch

If the watch escalates from Setting up… to Setup failed, your iPhone normally fixes this for you: it auto-registers the watch’s credentials on its behalf using the phone’s own (fresher) sign-in. Just open the iPhone app and give it a few seconds.

If it persists, sign in again on the iPhone (Settings → Home Assistant). A re-sign-in is only needed when both devices’ tokens were revoked at once — for example after a Home Assistant restore or a rotated long-lived access token — which is the one case the phone can’t auto-heal on its own.

Camera Issues

Black or won’t load? Check the camera works in HA directly. Try switching the stream mode to Snapshots (Settings → Watch Behavior → Camera Settings). Cameras work best on Wi-Fi.

Choppy? Use a slower refresh rate (3–5 seconds) and try Snapshots mode. Check your Wi-Fi signal.

FAQ

Does it need internet? Not for local connections. If your phone and HA are on the same network, no internet needed.

Can I use it without my iPhone nearby? Yes — if your watch has Wi-Fi or cellular and can reach HA directly or through Nabu Casa.

Does it drain watch battery? Normal use has minimal impact. Fast camera refresh, lots of animations, and high gesture sensitivity use more.

How many devices can I add? No limit, but 20+ tiles per page gets cramped. Spread them across pages.

Is my data sent anywhere? The app talks directly to your Home Assistant server — your URL, token, entity names, and states never leave the device. Anonymous app-usage analytics (PostHog) and crash reports (Firebase Crashlytics) are sent. No personal info, account IDs, or HA data is included. See Privacy Policy.

What watches are supported? Any Apple Watch on watchOS 11 or later. Hand gestures need Series 9, Ultra 2, or newer. Action Button is Ultra-only. Control Center widgets need watchOS 26 or later.

Can I use Siri? Yes — toggle devices, run scenes, set brightness, check states, and more. See Siri Shortcuts.

Can I back up my layout? Yes — export to a file, sync with iCloud, or share with family. See Backup & Restore.

Does it work with Nabu Casa? Yes. Enter your Nabu Casa remote URL as the server address. Make sure your subscription is active and remote UI is enabled.

Can I send voice announcements? Yes — use TTS quick menu for pre-set messages or Voice Broadcast to record and play live audio on your speakers.

Can I control devices based on my room? Yes — set up a room sensor and Wrist Assistant can auto-switch pages as you walk between rooms, jump to the current room with a gesture, or use Point Control to point at a device and twist, double-pinch, or tap to toggle it.