Appearance
Common Issues
Devices not appearing
| Symptom | Likely cause | Fix |
|---|---|---|
| Dashboard loads but shows no homes | Relay not connected | Check menu bar icon — see Relay Offline |
| Homes appear but no accessories | HomeKit permission not granted | See HomeKit permission below |
| Some devices missing | Free plan limit (10 accessories) | Upgrade to Standard — Account & Settings |
| Shared home has no devices | That home's relay is offline | The home owner's relay must be running |
Can't control a device
| Symptom | Likely cause | Fix |
|---|---|---|
| Toggle or slider doesn't respond | Device unreachable (offline) | Check if the device works in the Apple Home app first |
| Controls are disabled / "View only" | Your role is View | Ask the home owner to upgrade your role to Control or Admin |
| Error after toggle | Characteristic not writable | Some accessories expose read-only characteristics (e.g., sensors) |
Dashboard shows stale state
- The relay may have just reconnected — state updates within a few seconds
- Hard refresh the browser (Cmd+Shift+R or Ctrl+Shift+R)
- Check that the relay is connected (green menu bar icon)
Login issues
| Symptom | Likely cause | Fix |
|---|---|---|
| "Invalid credentials" | Wrong email or password | Double-check the email you signed up with |
| "Email not verified" | Verification link not clicked | Check inbox (and spam) for the verification email. See email verification. |
| OAuth redirect fails | Popup blocked or wrong redirect | Allow popups for homecast.cloud. Try a different browser. |
Email verification
- The verification email is sent on signup — check your spam/junk folder
- Gmail users: Check the Promotions tab
- Resend: A sign-in attempt will show a "Resend verification email" option
- Still not arriving? Check the email address for typos. If needed, sign up again with the correct address.
HomeKit permission
macOS should prompt for HomeKit access when the Homecast app first launches. If it didn't:
- Open System Settings → Privacy & Security → HomeKit
- Toggle Homecast on
- If Homecast isn't listed, try deleting and reinstalling the app
- Restart the Mac app after granting permission
Sharing issues
| Symptom | Likely cause | Fix |
|---|---|---|
| Invitation email not received | Check spam, or email typo | Re-invite with the correct email |
| "Invitation not found" when accepting | Already accepted or expired | Check if the home already appears in your sidebar |
| Share link shows "Access denied" | Link revoked or passcode required | Contact the person who shared it |
API-specific errors? API Errors
Relay connection issues? Relay Offline