Troubleshooting
Fixes for the most common problems.
Start with palmtop status in your project: it shows the daemon, the relay connection, the
project, the connected devices and whether an update is available.
The app says “PC offline”
The daemon on your computer is not connected to the relay.
- Is the computer awake? Run
palmtop status: any command starts the daemon if it isn’t running. Relay: connectingordisconnected: check the internet connection of the computer.- Did you delete
~/.palmtopai, or is that computer gone for good? The app can’t tell and keeps waiting: use Remove from this device and pair again. A project deleted on the computer, on the other hand, simply leaves the list on your devices.
“Palmtop on your computer is out of date”
The app is newer than palmtop on your computer. Run palmtop update.
“Update available” or “Relay: refuses this palmtop version”
Run palmtop update. It downloads the new version, checks it, updates the Claude Code skill and
restarts the daemon.
“Pairing link expired”
The QR page works once and for one minute. Run palmtop pair again, from any folder.
“That pairing link is not valid”
The link was cut or changed. Scan a new QR code from palmtop pair.
The agent doesn’t use palmtop
- Claude Code: run
palmtop install, then restart Claude Code. Ask explicitly, for example “put the checks on palmtop”, or type/palmtop. - Other agents: tell them to run
palmtop guidefirst (see Agents). palmtop: command not found:~/.palmtopai/binis not in yourPATH, see Getting started.
Agent errors
| Error | Meaning |
|---|---|
no session: pass --session <ref> |
The agent forgot --session <ref> |
no session "<ref>" in this project |
The session was deleted, for example from one of your devices |
no palmtop project in <path> yet |
Nothing was started in this folder: palmtop session start first |
The daemon doesn’t start
Check ~/.palmtopai/daemon.log, and that node --version is 22 or newer. port 4318 is used by another daemon means a palmtop started with a different PALMTOP_HOME is running: use the same
environment in every terminal.
Notifications don’t arrive
- Turn them on from the ⋯ menu of the project, on each device.
- iPhone and iPad: open the app from the Home Screen, not from Safari.
- They are not sent while the app is open on screen.
- Blocked in the browser: allow notifications for the site in the browser settings.