Troubleshooting

Find what you see and follow it to the fix. Start on the web console's Troubleshooting page: its Health checks catch most setup problems and give the command that fixes each.

Install & startupCopy Anchor Link

• The Linux host service won't start
• nvidia-smi says it can't communicate with the driver
• systemctl --user status punktfunk-web: unit not found
• pacman: database already registered
• The desktop won't start, or "GPU … not supported by EGL"
• The session fails right after editing host.env
• The game library is empty and the plugin runner has stopped
• Windows: the host or the web console won't start
• Windows: the status icon is missing after an update

The Linux host service won't startCopy Anchor Link

Usually an old hand-copied unit in ~/.config/systemd/user/ shadows the packaged one, and systemctl --user status punktfunk-host shows status=203/EXEC. Remove it:

rm ~/.config/systemd/user/punktfunk-host.service
systemctl --user daemon-reload
systemctl --user restart punktfunk-host

Any other failure: journalctl --user -u punktfunk-host -e names the reason.

nvidia-smi says it can't communicate with the driverCopy Anchor Link

The NVIDIA kernel module didn't load. With Secure Boot on (mokutil --sb-state), its signing key isn't enrolled yet. Import the key, reboot, and on the blue MOK Manager screen, at the machine itself, choose Enroll MOK → Continue → Yes, enter the password, then Reboot:

sudo mokutil --import /var/lib/shim-signed/mok/MOK.der    # Ubuntu
sudo mokutil --import /var/lib/dkms/mok.pub               # Debian (DKMS)
sudo akmods --force && sudo mokutil --import /etc/pki/akmods/certs/public_key.der   # Fedora

Or turn Secure Boot off in the firmware. Then cat /sys/module/nvidia_drm/parameters/modeset must print Y. If it doesn't, turn modesetting on, rebuild the initramfs and reboot:

echo 'options nvidia-drm modeset=1' | sudo tee /etc/modprobe.d/nvidia-drm.conf

Connection & discoveryCopy Anchor Link

• Another streaming host (Sunshine, Apollo, …) is installed
• The host isn't found on the network
• No client can reach a Windows host
• The host is asleep and won't wake
• Pairing is rejected, or the client can't connect
• A plugin's interface doesn't load

No client can reach a Windows hostCopy Anchor Link

Setup opens the host's ports on Private and Domain networks only, so a network Windows marks Public blocks every client. The host log warns about it at startup.

Set the network to Private in Settings → Network & internet → your network → Network profile type. Running the setup again offers the same switch. On a trusted network that has to stay Public, run this from an elevated PowerShell:

punktfunk-host service install --allow-public-network=on

It opens the streaming ports on Public networks; the console's ports keep their scope.

Picture & sessionCopy Anchor Link

• Black screen, but the client connects
• Black screen with sound (Windows)
• Capture fails: "Session creation inhibited" (GNOME)
• Games open on a physical monitor, not on the stream (Hyprland, sway, niri)
• Game Mode: black screen, or stuck at the box's resolution
• The picture freezes for a moment, over and over (Windows)
• Stutter, drops, or high latency
• The stream doesn't use the codec or HDR I picked

Input & controllersCopy Anchor Link

• My mouse and keyboard are stuck in the stream
• My keyboard types the wrong characters
• A controller is detected but games don't see it (Linux)
• The pad arrives as an Xbox 360 controller instead of a Steam Deck
• Stream lags, then freezes, with a DualSense pad (Bazzite, SELinux)
• A Steam Controller 2 is captured, but Steam doesn't list it
• Copy and paste between host and client does nothing

AudioCopy Anchor Link

• Audio stutters, and only the audio (Linux)
• Streamed audio sounds worse than on the host (Windows)
• Audio lags behind the picture
• I hear myself

Still stuck?Copy Anchor Link

Collect the logs in one file and file a report: Reporting an Issue. The console's Troubleshooting page shows the host's recent log at debug detail, whatever the log level, and a Sources filter for plugin output.