Documentation

Troubleshooting

Most problems have a plain cause, and Home Stream usually knows what it is. This page covers the common ones and where the server writes down what it knows.

A film or episode won't play

Home Stream doesn't convert anything as it plays. It sends the file exactly as it is on the drive, so if a device can't open that file, it can't play it.

When the server finds a file that nothing can play, it records why. The Play button says Cannot Play, the reason is written beneath it, and the poster carries a Can't play mark. These are the reasons it recognises:

• A container no player can open: AVI, WMV, ASF, FLV, RM, RMVB, DivX, VOB, MPG and MPEG. When the video inside is H.264, the server says so, because that file can be repackaged as MP4 without re-encoding. When it is DivX or XviD, it says that would play if it were in an MP4.
• A video format no player can decode: Windows Media Video, VC-1, Microsoft's early MPEG-4 versions, RealVideo and Flash video. These need converting to H.264 in an MP4.
• The file has no index. This usually means a conversion was interrupted, and the file needs making again.
• The file isn't readable as video. It may be damaged or incomplete.
• The file couldn't be read in time. It may be damaged, or not a video at all.
• The server isn't allowed to read the file. Check that it belongs to the user named in HOST_UID, or that that user can read it.
• The file is no longer on the drive.

The safest format is an MP4 file with H.264 video and AAC audio. Once you have a working copy, a curator can choose Replace File… from the title's menu to swap it in. Watch history and favourites stay attached.

Deleting a file that won't play isn't immediate. It goes to the Trash, because files that won't play are often the easiest to rescue.

A song won't play

The server doesn't check songs the way it checks video, so there won't be a reason shown. If one song or album won't play on a device, the format is the likely cause. Converting it to a widely supported format such as AAC or MP3 is the usual fix.

An app says it can't connect

1. Is the server running?

   On the server, docker ps should list homestream as healthy. From the device that can't connect, open http://your-server:8080/health in its web browser. If you see a version number, the server is up and reachable from that device.

2. Is the device on the same network?

   Home Stream only works on your home network. A phone on mobile data, or on a guest Wi-Fi network that is kept apart from the rest, can't reach it.

3. Has the app been allowed onto the local network?

   iPhone and iPad ask before an app may talk to devices at home. If that was declined, turn it back on under Settings → Privacy & Security → Local Network on the device.

4. Is the address right?

   It starts with http://, not https://, and ends with the port, normally :8080. If you used a full domain name and the server replied "This server does not answer to that name", see the security page about the names the server answers to.

5. Read the server log

   An app often reports any failure as "can't connect", even when the server answered with an error of its own. The log shows which it was.

A folder says Not connected

In Settings → Library Folders, Not connected — not being scanned means the folder is missing or empty. Scans skip it, and nothing in it is marked missing, because a drive that isn't there tells the server nothing about your files.

Check that the drive is plugged in and mounted, and that the folder is listed under volumes in compose.yaml. If the drive was mounted after the server started, restart it with docker compose restart. Then press Check beside the folder, and run a scan. If the drive now lives at a different path, use Re-point….

New Folder says a folder can't be made

New Folder in Browse refuses system folders and the server's own folders. Make the folder on your media drive instead. If it says the server isn't allowed to make a folder, the place is outside what the server can write to: on a server installed with Docker, that is anywhere other than your media drive.

The next episode starts before the credits end

The next episode is offered 30 seconds before one ends, and starts when the countdown finishes. A curator can make it 60 or 80 seconds for everyone, under Settings → Server → Next Episode Countdown. To stop it altogether, turn off Settings → Preferences → Play the next episode automatically; that's per person. The Apple TV doesn't show a countdown yet: it plays the next episode when one ends.

Something is missing after a scan

A scan that you start marks anything it can't find as missing. It doesn't remove it. Watch history, favourites and playlists are kept, and when the file comes back, the next scan finds it again as though nothing had happened.

A lot of missing items at once is almost always one drive that isn't connected. Check the folder they are in, then scan. Scans that run on a schedule only ever add things. They never mark anything missing.

The scan also tells you about files it skipped. These are files in formats the server doesn't read, and files that hold more than one episode. Split those into separate files and the missing episodes appear.

The wrong title or poster

Matching is a guess made from the file name, and sometimes it guesses wrong. See Matching and metadata for how to put it right.

The banners at the top of the page

The web interface tells you about a few things without being asked:

• Library problems, shown to curators. It covers items not on the drive, items that can't be played, possible duplicates, and files holding more than one episode. Show me lists them. Not now hides the banner until the set of problems changes.
• Storage low or full, shown to curators. See The disk is filling up below.
• This page and the server are different versions. See below.
• Add a second step to your sign-in, shown to any account without two-factor sign-in, until you set it up or decline it.

Reading the server log

On the server, from any folder:

docker logs --tail 200 homestream

To watch new lines as they arrive, use docker logs -f homestream and press Ctrl-C to stop. The log keeps about the last 30 MB, and older lines are cleared away on their own.

When something goes wrong, the web interface often just says "Something went wrong." The detail is in the log.

Finding the setup code

A new server prints a setup code to its log. On the server, run:

docker logs homestream 2>&1 | grep -A3 "setup code"

The code is also in setup-code.txt in your data folder. It stays the same across restarts and is deleted once the server has been set up.

If setup says "The server can only be set up from your local network", use another computer, phone or tablet on your home network. Open the server by its IP address, the four numbers separated by dots, which the installer shows. A browser on the server machine itself is refused, so that nobody outside the house can pose as it.

"This page and the server are different versions"

The page in your browser came from a different release than the server now answering it. Nothing has been lost. Press Reload. If the banner comes back, restart the server with docker compose restart, then reload again.

A separate warning can appear under Settings → Server → Software Update, beside the database schema. It names what to do. Usually that is to update the server, or to check the log if the database's upgrade didn't finish.

The disk is filling up

Curators see a warning before a disk fills. The disk holding the database is judged more strictly than one holding only media, because running out of room there can stop the database saving changes. When space is critical, the warning can't be dismissed, and the server stops downloading artwork to protect the database.

• The data folder is on a small SD card. This is the most common cause. Move the data folder to a bigger drive, as described in Backup, restore and moving.
• The Trash hasn't been emptied. Deleted media stays on the drive until you empty it. Open Trash in the sidebar and choose Empty trash. This removes the files for good.
• Old Docker images have built up. Each automatic update leaves the previous image behind. docker image prune removes old images that no longer have a name. It does this for every container on the machine, not only Home Stream.
• The log is already capped at about 30 MB by the supplied compose.yaml, so it won't grow without limit.

Updates aren't happening

Home Stream can't update itself. The machine does it, using a small timer you install once. If Settings → Server → Software Update says No check recorded yet, that timer isn't installed or isn't running.

• Run the installer again and answer yes to installing updates automatically.
• The timer expects compose.yaml and .env in a folder called homestream in that user's home folder.
• It only acts during the hour you chose, so a check won't show until that hour has passed.
• If HOMESTREAM_IMAGE names a specific version rather than :stable, there is nothing newer to fetch. That is the point of naming a version.

To check the timer on the machine, replace you with the user it runs as:

systemctl list-timers [email protected]
journalctl -u [email protected] -n 20

A forgotten password

Someone else in the household

The administrator can set a new password for them under Settings → Users & Devices, using Set Password… beside their name. Accounts that sign in with Apple have no password to forget.

A lost phone, with two-factor sign-in on

Use one of the backup codes you saved when you set it up. Each one works once.

The administrator's own password

Because no email is involved, getting back in is proved by having access to the machine Home Stream runs on.

1. Read the recovery code

   On the server, run docker exec homestream cat recovery-code.txt. The code is also in recovery-code.txt in your data folder. If that file has gone, restarting the server writes a new one.

2. Open the sign-in screen from your home network

   Use a different device from the server itself, and open the server by its numeric address. Choose I have lost my password.

3. Set a new password

   Enter the username, the recovery code and a new password of at least ten characters.

Two-factor sign-in is turned off for that account and every device it was signed in on is signed out. You can turn two-factor back on once you are in. The recovery code is replaced as soon as it has been used, so read the new one next time. Recovery only works from your home network, and repeated wrong guesses are slowed down.