PennyOS guide

Troubleshooting

The problems people actually hit, what causes each, and the fix.

The touchpad does nothing

The optical sensor can hang, and a reboot does not reset it because the keyboard controller keeps it powered. Slide the power switch off and on. It happens most often after a long sleep that began with an End Call hold, which is why the switch is the recommended way to shut down.

Do not try to diagnose it by reading the trackpad registers from the Pi. A read the sensor never answers can hang the keyboard controller until the next power cycle, taking the keyboard with it.

The touchpad jumps several rows

Set Settings > Touchpad > Touchpad to slower. PennyOS also ignores an arrow that repeats within 90 ms or reverses within 250 ms, which is a flick, not a keypress. If a setting row says NOT APPLIED, the driver refused the change; rerun sudo ./install.sh --no-drivers to restore the file permissions it needs.

Ctrl+t does not come back from the terminal

It is not meant to. Return with the tmux prefix, End Call, then p.

The Wi-Fi list is empty or a network will not join

The shell asks NetworkManager for a scan and a join, and NetworkManager asks polkit first. The installer adds a rule that allows it. If the rule is missing, rerun the installer. The Pi only sees 2.4 GHz networks.

An app says it cannot reach the mini

"The mini" is your server. Check, in order:

1. The status bar: is there Wi-Fi, and does the server mark appear?
2. mini_host, mini_user and vault_path in /etc/pennyos.conf.
3. The gate log on the server, ~/.config/pennyos/gate.log. A refusal is logged with the exact command, which tells you whether the device's request reached the server and why it was turned away.
4. Away from home, whether Tailscale is up on both machines.

Mail says it is not configured

The mail account lives on the server in ~/.config/pennyos/mail.conf. See Mail for both ways to set it up.

Store says there was no answer

Store's data covers San Francisco only. If your fix is elsewhere, Near has nothing to show. Change the fix with l in Weather.

Store's Near list at a San Francisco fix. Outside the city, this screen says the fix may be outside San Francisco.

Locate did not move my position

When BeaconDB does not know the Wi-Fi networks around you, the only answer left is the city your internet address appears to be in, which can be the wrong city. PennyOS shows that guess and deliberately does not apply it. Set the place by name in Settings > Location instead.

A screen shows a crash message and returns Home

That is the shell protecting itself: when an app throws an error, PennyOS closes that app, shows the error briefly, and keeps running. The full traceback is in the journal: journalctl -u pennyos.service.

I forgot my PIN

If the card is encrypted, its data cannot be recovered. Erase the card and install again. Your vault mirror will come back on the first sync; notes and journal entries that never synced will not.

I lost the device

On your server, delete the device's lines from ~/.ssh/authorized_keys, including the boot key line if you set one up, and remove the device from your tailnet. It can then reach nothing, and without your PIN the card stays closed.