GuppiDocs
Get started
Documentation menu

Troubleshooting

First moves#

curl http://localhost:8000/health        # is the hub answering?
systemctl status postgresql              # the one system service

If the hub isn't answering, look at the terminal you started guppi hub in — that's where all the server logs are (Guppi runs in the foreground, not as a background service).

/health should return {"status":"ok","mode":"local","postgres":"ok"}. When filing a bug, include the release version (cat /etc/guppi/version) and the last screen of guppi hub output.

Install failed partway#

The installer is idempotent — fix the cause and re-run it. Common causes:

  • PostgreSQL >= 15 required — you're on an older Debian/Ubuntu. The installer adds the pgdg repo automatically; if that failed, add it manually and retry.
  • No network / GitHub unreachable — the installer downloads release assets from github.com; it needs internet once, at install time. The bench runs offline afterwards.
  • No public release found — you're ahead of us; check the releases page exists and has assets, or pin one with GUPPI_REF=v0.1.0.

Dashboard doesn't load#

  • Is guppi hub running? The dashboard only exists while the hub runs — in the terminal you started it in. It does not come back on its own after a reboot or after that terminal closes; start it again with guppi hub.
  • Page loads but says API-only / plain 404s: the UI bundle wasn't installed — re-run the installer (it fetches guppi-ui-local.tar.gz from the release).
  • Loads but shows no live data: check the guppi hub terminal for NATS errors; the browser connects to port 9222 (WebSocket) on the same host — a firewall between you and the Pi must allow 8000, 9222, and 3010.
  • Loads in one browser but not another: some browsers silently upgrade http:// to https:// (the hub doesn't serve TLS) — disable "always use secure connections" for this site, and check Shields/VPN/proxy extensions.

Rig doesn't appear#

  • Is guppi rack actually running on the bench machine, and did it print a scan result? Instruments must be visible to it (USB permissions, Ethernet segment).
  • A USB instrument visible to the OS but missing from the scan can be a permission problem: the rack installer grants serial/USB access via udev rules and applies them to already-attached devices. If the installer printed a udev warning, replug the instrument (or reboot) so the rules apply, then restart guppi rack.
  • Separate rack machine: it must reach the hub — curl http://<hub>:8000/health from the rack box. If you paired against a raw LAN IP and the hub's address changed with a DHCP lease, edit ~/.guppi/config.env to the .local mDNS name and restart guppi rack.
  • Claim code entered but "rig offline": the rack keeps retrying — give it ~10 s, then check the rack terminal for connection errors.

Rig is in the wrong place (cloud)#

  • Paired a rig under the wrong organization, or under your personal account instead of the team's? On the rigs overview in Guppi Cloud, hover the rig's card and use the transfer arrow — move it to one of your other orgs, or send it to another user by email (that also hands over pairing ownership). History moves with the rig. Only the account that paired the rig can transfer it — so if a teammate paired it, they run the transfer.

Charts stop / data missing#

  • Telemetry is retained indefinitely — history is never auto-deleted, so missing charts are not a retention issue. Check the rack is connected and publishing, and that the signal path still matches.
  • Check disk space: df -h /var/lib/guppi. A full disk stops ingest. Because history is kept indefinitely, reclaim space by pruning channels you no longer need from the Storage tab.

Ports in use#

Guppi assumes 8000 (hub), 4222/9222 (NATS), 3010 (PostgREST), and Postgres on its distro default. If something else owns one of these, stop it or ask in an issue — ports aren't configurable in v0.

Starting over#

# stop the hub first (Ctrl-C in the terminal running it)
GUPPI_PURGE_DATA=1 guppi uninstall

then re-run the installer. This deletes all recorded data. (Equivalent, if guppi itself is broken: curl -fsSL …/install.sh | sudo GUPPI_PURGE_DATA=1 bash -s -- --uninstall.)