Troubleshooting

Troubleshooting

Problems people run into, and what fixes them. For problems with a remote player's sync, see the table at the end of Syncing a Remote Player.

Where to look first

The server's log has everything the container does:

docker logs --tail 100 station-wrapper-43

Look for one part of it by its name, for example the pool or the keeper:

docker logs station-wrapper-43 2>&1 | grep -i keeper | tail

The dashboard's Status page lists warnings, each with a button to the page that fixes it.

The server

The container won't start, or the catalog acts strange. data/ is probably on a network share. The schedule database (SQLite) misbehaves over a network, and most shares can't hold symlinks. Move data/ to the server's own disk.

A new channel doesn't show up in Emby or Jellyfin. Channels made by a script need the guide refreshed once:

curl -s 'http://192.168.1.20:5004/xmltv.xml?refresh' > /dev/null

Then, in Emby or Jellyfin, refresh the guide data (Live TV settings). Channels made on the Stations page show up by themselves after a short wait.

A channel plays the test pattern. Its lists have no videos for that time slot, or its schedule ran out. The Stations page warns when a channel has less than a day left. Make sure Keep schedules going is on.

Building a loop channel fails with LiquidLoopBlock requires content. A loop station only plays videos sitting directly in its folder, not in subfolders. See Making Channels.

New episodes never show up. Go down this list:

1. Is the show's library folder in SYNC_INCLUDE in the compose file? If not, the wrapper can't see it.
2. Was the folder added with Keep folders up to date ticked? Check the Kept up to date list on the Lists & files page.
3. Has 4 am passed since the episode arrived? That's when channels pick up new videos. Press Update videos on the station to do it now.
4. Is days ahead high? New videos only play on days the keeper adds after the update. With 7 days ahead, that's a week away.

The guide has no show names or posters. Check the MEDIA_SERVER_API_KEY in .env, and the MEDIA_SERVER_URL. If the log says none of the files are below some folder, fix MEDIA_SERVER_MEDIA_ROOT. It must be the folder where Emby or Jellyfin sees the same videos.

You can't read data/config/tuner/sources.json (permission denied). The wrapper saves a few files so only root can read them. Read them through the container instead:

docker exec station-wrapper-43 cat /config/tuner/sources.json

Shows start at the wrong hour. The container uses the server's time zone through /etc/localtime. Check it with timedatectl. A remote player must use the same time zone.

Things not to do

• Don't put port 4242 on the internet. FieldStation42's console has no login. Port 5004 has the dashboard login, but it's still best kept on your own network.
• Don't run the project's test suite inside your running container. Some tests write over /config/tuner/config.json, which is your real settings file. If you want to run the tests, start a separate, throwaway container that points FS42_TUNER_CONF at a temporary file.
• Don't write into your media folders. The wrapper only ever reads them, and everything it makes is links in data/catalog. Keep it that way, so your media server's libraries stay clean.
• Don't "follow" a folder into a loop channel's list. The new videos land in subfolders, and a loop never plays them.

The remote player

The TV is black after boot. Log in over SSH and read the player's log with journalctl -t fs42 -n 50. If the player crashed, the autologin restarts it every few seconds. The log shows why it keeps stopping.

The picture is cut off, or has black bars. That's the panscan setting. See the table in Syncing a Remote Player.

Booting takes two minutes. If the PC has a network port with nothing plugged in, Ubuntu may wait for it. Tell it to continue once any port is up:

sudo mkdir -p /etc/systemd/system/systemd-networkd-wait-online.service.d
sudo tee /etc/systemd/system/systemd-networkd-wait-online.service.d/any.conf <<'EOF'
[Service]
ExecStart=
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any -o routable --timeout=90
EOF
sudo systemctl daemon-reload