Fixing problems

Most problems are about reaching the household’s computer. Start with the doctor: on that computer, run sudo homefellow doctor. Owners also see it in the app’s Settings, under the server. It checks everything and says what’s wrong in plain words, with the fix.

“Can’t reach the household”

Work through these in order.

1. Is the household’s computer on and awake? If it’s a laptop or a desktop that sleeps, the family can’t reach Homefellow until it’s awake.

2. Is Homefellow running? On the household’s computer, sudo systemctl status homefellow should say “active (running)”. If not, sudo systemctl start homefellow, then look at journalctl -u homefellow -e for the reason.

3. At home, the firewall is the usual cause. If the computer has a firewall on, it may block your phones. Run sudo homefellow access firewall to see, with the exact command that lets them through, such as:

   sudo ufw allow 8788/tcp comment 'Homefellow'
   sudo ufw allow 8789/udp comment 'Homefellow'

   On Windows, your home network has to be set to Private, not Public: in Settings, then Network & Internet, open your network and choose Private.

4. Away from home, check the relay. If you turned on “reach it from anywhere”, the doctor checks Homefellow’s relay and says if it can’t be reached. In the app, Settings shows “From anywhere” and whether it’s in use.

5. Did the household’s computer move to another address? The apps keep every address the invite carried. If you changed the network, the computer’s name or Tailscale, give the device a fresh invite.

The setup code doesn’t work

• The code is on the household’s computer: run sudo homefellow setup-code. It’s printed when Homefellow starts too.
• Capitals and the hyphen don’t matter. abcd2345 works as well as ABCD-2345.
• After five wrong codes, it waits a few minutes before taking more.
• “Already set up” means the household exists. The code is spent. Sign in with an invite instead.

An invite doesn’t work

• “Already been used”: each invite signs in one device. Ask an owner for a new one.
• “Expired”: invites last three days. Ask for a new one.
• “Withdrawn”: an owner took it back. Ask them for a new one.
• A page saying to get the app: that’s homefellow.org/join. Install the Homefellow app, then open the invite link again (or use “Copy the invite” and paste it into the app). The invite never leaves your phone.
• “This invite link looks incomplete”: part of the link was cut off, often by a messaging app. Ask for the link again, or scan the QR code inside the app.
• A certificate warning in the browser: that’s expected on the home network, because the household uses its own certificate. Use the Homefellow app instead, which checks the certificate against the invite.
• “Open Homefellow in its app” in a browser at home: at home, Homefellow is for the apps. Use the app, or the household’s Tailscale address in a browser.

The AI isn’t working

• “Failed: the reading model didn’t answer”: the model server isn’t running, the address is wrong or the model isn’t loaded. The message says which address it tried. Start the server (for example open Ollama), then run sudo homefellow models test again.
• “It answered, but never with something Homefellow could use”: the model is running but isn’t following Homefellow’s instructions. Try a larger or newer model.
• “Too small”: the model missed things in the test. Homefellow needs a model of about 30 billion parameters or more to read reliably. See the AI models.
• “Slow”: it works, but slowly. A faster computer helps, or a smaller model that still passes the test.

What the doctor’s checks mean

Check	What it looks at
Setup	whether the household is set up
The reading model, the questions model	whether each AI model answers
Goose	the tool Homefellow uses to talk to the AI, at the version it should be
The model test	the last test of the models and how it went
Voice	whether spoken answers can be turned into text
Disk space	room for the household’s data and backups
The household’s time zone	that dates and reminders use the right one
Calendars	that connected calendars are syncing
Reaching it from your devices	that the household’s addresses answer
The firewall	whether the firewall lets your phones through at home
The home-network certificate	the certificate the apps check at home
Devices without the fingerprint	devices that joined before home-network access was on; each needs a fresh invite
Reaching it from anywhere	whether the relay can be reached
Backups	that a recent backup exists and would restore
A restore	a restore waiting for the next start, or the last one done
Version	which version is running

Each one is ok, a warning or a problem. A problem always comes with a fix.

Still stuck?

Ask your AI assistant, with this site’s address: see set up Homefellow with your AI assistant. It can run the doctor with you and read what it says.