Hometether docs
v1.0.0
Get help
● Ship

Troubleshooting
common problems and fixes.

Cases that follow from the code, with what to check. Because the TV drivers have not run on real TVs, the first group is the most likely one.

TVrelayserverbuild

01No TV is found

Check that the phone and the TV are on the same Wi-Fi, that the TV is on, and that the network does not block devices from seeing each other (guest networks often do). Then type the TV's address, for example 192.168.1.20; it must be a private address on your Wi-Fi. On iPhone, automatic search needs Apple's Multicast Networking entitlement (Release); typing always works.

02The TV is found but does not react

  • Roku: in the Roku settings, "Control by mobile apps" must be on.
  • Samsung: choose Allow on the TV when the prompt appears. If you denied it earlier, remove the phone in the TV's device list and try again.
  • LG: "LG Connect Apps" must be on, and the TV asks to pair. The pairing uses an unsigned manifest that some webOS versions may reject. This is a known risk of the unverified driver.
  • Details differ per TV model and were never checked on a real TV: expect to adjust the driver in app/lib/src/tv/ for your model.
  • A button says "not available on this TV" or "not supported yet": see TV support for what each brand offers.

03Android TV or Google TV is listed but cannot be controlled

These TVs are found on the network but control is not supported yet in this version.

04Remote help is missing or says it is off

The app was built without API_BASE_URL, or the feature or the relay is switched off in the console (App config: features, Relay), or the relay has no reachable address. Rebuild with --dart-define=API_BASE_URL=https://... and check Overview in the console.

05The helper sees "phone is not open"

Help can only start while Hometether is open on the parent's phone. There is no push notification in this version. Ask the parent to open the app.

06Pairing works but the relay never connects, or drops after a minute

Your proxy is probably not passing WebSocket upgrades on /v1/relay, or its idle timeout is below 60 seconds (the app pings every 25 seconds). See Relay. Also check that the address is https; a plain http address does not work on current phones.

07"Code not valid"

A code works once and expires (10 minutes by default). An already used, expired and mistyped code all give the same answer on purpose. Ask the parent for a new one. After many wrong tries from one address the server answers 429 for a while.

08"A session is already running" or "daily limit"

Only one session per family runs at a time. The daily limit (default 20 sessions per family) and the other limits are in the console under Relay.

09429 errors, or everyone shares one address

Behind a proxy set TRUST_PROXY_HOPS=1, otherwise all users look like the proxy's address and share one limit.

10The paywall says "Not set up yet"

No product id is set for this platform. Fill the ids in the console or brand.dart (Where to put the ids). Ids must match App Store Connect and Play Console exactly. For test purchases on Android, install from a Play test track as a licence tester.

11Purchase verification answers 501

501 verification_off means verification is not switched on under Purchases, so the app trusts the on-device result.

12I cannot find the console setup code

It is printed in the server log at start when ADMIN_SETUP_TOKEN is empty. In Docker run docker logs <container>. Or set ADMIN_SETUP_TOKEN in .env and restart.

13npm ci fails or better-sqlite3 will not load

Use Node 26 LTS, or 22.12 or newer (node -v). better-sqlite3 is a native module: if no prebuilt file exists for your system you need build tools (Python 3, make, a C++ compiler). Delete node_modules and run npm ci again after changing Node versions.

14A console change does not appear in the app

The config is cached for 5 minutes. Wait, then reopen the app. Check that the app was built with API_BASE_URL and that the address is reachable from the phone.

15Play rejects the upload or says the app is debug-signed

As shipped, release builds use the debug key. Add your own signing config (Release).

16Xcode says signing failed or the bundle id is not available

The project ships with no team set. Choose your own team and a bundle id you own (Rename).