punktfunk/docs-site/content/docs/troubleshooting.md at 7bf2899301a782a400e06445431d4a440c5ca6cb

Files

T

enricobuehler 9e015304ee docs(dist): end-user install front door + serve/pairing/firewall accuracy fixes

Make the host docs match the real distribution path and the actual CLI. Reviewed by a
multi-agent pass (6 editors against one verified fact sheet + an accuracy reviewer); its
findings (a wrong client-Recommends claim, a native-concurrency overstatement) folded in.

- Install front door: new README "Install (host)" method-picker + docs-site/install.md
  (+ nav), routing each distro to its package registry; source build demoted to a fallback.
- Registry-first install: ubuntu-gnome/ubuntu-kde now lead with the apt registry (not a
  cargo build); bazzite leads with the Gitea RPM registry (was COPR/source). Source builds
  moved to an appendix.
- CLI accuracy: serve --native arms pairing from the web console (NOT --allow-pairing, which
  with --require-pairing/--max-concurrent is m3-host-only); --open disables mandatory pairing.
  host-cli/configuration/pairing/quickstart/troubleshooting corrected; mgmt API documented as
  always HTTPS+token. Native host serves one session at a time (extras queue) — not multi.
- Firewall: real ports documented (native UDP 9777 + the ephemeral data port caveat +
  GameStream ports) for Debian + Arch (ufw + nftables), not just Bazzite.
- Sync/accuracy: punktfunk-client (GTK4) presented as a shipping client (not "roadmap"),
  punktfunk-client-rs as the headless tool; host Recommends punktfunk-web only (not the
  client); COPR chroots f43/44; bootc header says Gitea registry not COPR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-15 10:43:12 +00:00

3.5 KiB

Raw Blame History

title, description

title	description
Troubleshooting	Common problems setting up or using a punktfunk host, and how to fix them.

The host isn't found on the network

Make sure the host is actually running (systemctl --user status punktfunk-host, or you see it listening in the terminal).
Host and client must be on the same network/subnet. Discovery uses mDNS, which doesn't cross routed subnets or most VPNs-without-multicast. As a fallback, add the host by IP address in your client.
A firewall on the host can block it. The native protocol's control plane uses UDP port 9777. The per-session data plane uses an ephemeral UDP port negotiated at connect time (currently random) — for a strict firewall, open a UDP range or move the data port. GameStream/Moonlight uses TCP 47984/47989/48010 + UDP 47998–48010 + ENet UDP 47999. Allow them on the host's firewall.

`nvidia-smi` says it can't communicate with the driver

The NVIDIA kernel module didn't load. With Secure Boot enabled, enrol the module's signing key: sudo mokutil --import /var/lib/shim-signed/mok/MOK.der, reboot, Enrol MOK at the blue screen (or disable Secure Boot). On Fedora, follow RPM Fusion's Secure Boot steps.
After a kernel update the module may need a rebuild — reinstall the driver package.

The desktop won't start, or "GPU … not supported by EGL"

The NVIDIA GL/EGL userspace is missing — the base driver package doesn't always include it.

Ubuntu: sudo apt install libnvidia-gl-<version> (matching your driver).
Confirm /usr/share/glvnd/egl_vendor.d/10_nvidia.json exists and nvidia-drm modeset is Y.

Black screen / no picture, but the client connects

You must be on a Wayland session, not X11 (check the login-screen session picker).
KWin must be ≥ 6.5.6 (kwin_wayland --version); GNOME ≥ 48; gamescope ≥ 3.16.22.
Confirm PUNKTFUNK_COMPOSITOR in host.env matches your desktop.

Capture fails: "Session creation inhibited" (GNOME)

A locked GNOME session blocks screen capture. On an always-on/headless host, disable the lock:

gsettings set org.gnome.desktop.screensaver lock-enabled false
gsettings set org.gnome.desktop.session idle-delay 0

See Running as a Service.

A controller is detected but does nothing (Bazzite)

The host user needs to be in the input group. On Bazzite:

ujust add-user-to-input-group

Then log out and back in. On other distros this is sudo usermod -aG input $USER + re-login.

Pairing is rejected / the client can't connect

The host requires pairing by default. Arm pairing from the web console, then enter the PIN on the client. See Pairing & Trust.
If you re-installed the host, its identity changed — re-pair the client.

Stutter, drops, or high latency

Lower the bitrate. On a busy or Wi-Fi link, the requested bitrate may be too high — the Apple app's speed test picks a safe value; with Moonlight, set it manually.
Prefer a wired connection or 5 GHz Wi-Fi between host and client.
Streaming to many devices at once shares the GPU encoder. The production host (serve --native) handles one native session at a time, with extra clients queued; heavy load is usually bitrate-bound, so lower the bitrate first.

Still stuck?

Run the host with RUST_LOG=info (or debug) and check journalctl --user -u punktfunk-host for the error around the failed connect or capture.

3.5 KiB Raw Blame History Unescape Escape