Common Pitfalls

Common Pitfalls & Troubleshooting

The traps that caught us while building and running BoatOS — with symptom, cause and immediate fix. Not an invented textbook, but what actually happened.

Much of this only affects a self-build or rebuilding the image yourself. If you flash the ready-made image, you usually never hit the networking traps, because the image already works around them.

---

After disconnecting WiFi, all online services are dead

Symptom: Water levels vanish from the chart, the version/update check reports "unknown", weather stops arriving. The backend log shows Temporary failure in name resolution. Often triggered right after Settings → WiFi → Disconnect.

Cause: NetworkManager (which manages wlan0) rewrites /etc/resolv.conf on disconnect and removes all nameservers — even when eth0 (wired LAN) is still connected. DNS resolution is dead system-wide, even though the network connection itself is fine.

Immediate fix:

sudo systemctl restart dhcpcd

dhcpcd then re-adds the router DNS from the wired lease.

Permanent (solved in the current image): NetworkManager no longer manages resolv.conf (dns=none), dhcpcd is the sole writer, and a fallback to 1.1.1.1/8.8.8.8 is appended to every resolv.conf.

Rule for any network diagnosis: check DNS first, everything else second. If ping 1.1.1.1 works but ping github.com doesn't → this is the trap.

---

Two IP addresses on WiFi

Symptom: The Pi has two IPs on wlan0 at once (one "secondary"). Both seem to work, but the connection is flaky and the DNS trap above happens more often.

Cause: In /etc/dhcpcd.conf, denyinterfaces wlan0 was placed after an interface wlan0 block. In dhcpcd, everything after an interface line belongs to that block — so the global deny was swallowed. dhcpcd grabbed a second lease alongside NetworkManager, and the router handed out two addresses.

Fix: Put denyinterfaces wlan0 and noipv4ll before all interface blocks; remove the interface wlan0 block entirely (NetworkManager owns wlan0). Verify:

pgrep -a dhcpcd            # should show only an eth0 worker, none for wlan0
ip -4 addr show wlan0      # exactly one inet line

Ground rule: dhcpcd manages only eth0, NetworkManager only wlan0. Don't blur this split — otherwise two DHCP clients fight over leases, routes and DNS.

---

After reboot: empty dashboard or empty logbook in Helm

Symptom: Right after a restart, Helm shows "No dashboard layout configured" and an empty logbook archive — even though the data is present in the backend.

Cause — a boot race: The display (flutter-pi) starts immediately; it needs no network. The backend, however, waited on network-online.target, which under a sluggish network can take over a minute. So Helm queried the dashboard and logbook into the void and gave up too soon.

Fix: The backend was decoupled from the network target (it starts with the display; the GPS reader connects afterwards), and Helm now retries indefinitely instead of just for a few seconds. Included from v1.8.0-rc7.

If it still happens: wait a moment — Helm heals itself on the next poll cycle once the backend answers. No restart needed.

---

Helm map renders incompletely — grey corners, missing tiles

Symptom: The map in Helm stays partly grey, the top-left corner is missing, and panning/zooming produces ever more blank tiles. Happens even on the plain base map.

Cause: Not the app code. flutter-pi holds the graphics memory (CMA on the VideoCore GPU). Many lightdm restarts in quick succession — typical during an intense deploy session — fragment that memory until texture allocation for new tiles fails.

Fix: Do one full reboot, not just lightdm:

sudo /sbin/reboot

For deploying: after a handful of Helm deploys, don't keep restarting lightdm — do one full reboot instead. The degraded GPU state is not visible in the code, and chasing it there costs hours in the wrong place.

---

Screen can't be turned off in software

Symptom (self-build, 24/7 installation): The Pi should run continuously and collect data, with only the screen off. But vcgencmd display_power 0 has no effect, and xset/DPMS neither.

Cause: On this setup (Pi 4, HDMI, flutter-pi) software display-off simply doesn't work: flutter-pi holds the DRM master under KMS, there is no X11 for DPMS, the HDMI monitor has no backlight sysfs, and it isn't on the CEC bus either.

Solution: A relay on the display's 12 V supply, switched via GPIO — definitively 0 W and independent of the display stack. The data layer (mosquitto, signalk, boatos) already runs as separate services, independent of the display. Details in docs/hardware-24-7.md. (Branch v1.9, not in the stable image yet.)

---

boatos.local won't load in Firefox but works in Chrome

Symptom: The address boatos.local times out in Firefox, while Chrome opens it instantly.

Cause: Firefox with DNS-over-HTTPS can't resolve the .local mDNS name. Not a BoatOS bug.

Fix: Use Chrome, or enter the IP address directly (e.g. http://192.168.x.x:8000).

---

Handy diagnostic commands

# DNS first — the most common cause of "everything online is dead"
ping -c1 1.1.1.1 && ping -c1 github.com

# Is exactly one dhcpcd worker running (eth0 only)?
pgrep -a dhcpcd

# Who holds the graphics card?
sudo fuser -v /dev/dri/card1

# Live backend log
journalctl -u boatos -f

---

Related: Hardware · First Start · Glossary