Troubleshoot LinScreen and Wayland Screenshot Portals

1. Confirm session and application

linscreen --version
printf 'session=%s desktop=%s\n' "$XDG_SESSION_TYPE" "$XDG_CURRENT_DESKTOP"
printf 'wayland=%s display=%s\n' "$WAYLAND_DISPLAY" "$DISPLAY"

Keep this output. A Wayland session normally exposes XDG_SESSION_TYPE=wayland and a Wayland socket.

2. Inspect portal services

systemctl --user status xdg-desktop-portal.service
systemctl --user --type=service | grep xdg-desktop-portal
journalctl --user -u xdg-desktop-portal.service --since "10 minutes ago"

Look for a desktop implementation such as GNOME, KDE, GTK or wlroots. The correct choice depends on the environment.

3. Verify desktop registration

test -f /usr/share/applications/org.linscreen.LinScreen.desktop
grep -E '^(Name|Exec|Icon)=' /usr/share/applications/org.linscreen.LinScreen.desktop
gtk-launch org.linscreen.LinScreen

The AppImage does not install global registration by default. The Debian package uses /usr/bin/linscreen.

4. Isolate capture mode

linscreen full --path ~/Pictures/linscreen-full.png
linscreen screen --number 0 --path ~/Pictures/linscreen-monitor.png
linscreen gui

Record which mode fails. Include display resolution, position, scale and rotation for monitor-specific problems.

5. Use the project debug helper

cmake -S . -B build-wayland-debug \
  -DCMAKE_BUILD_TYPE=Debug \
  -DLINSCREEN_DEBUG_CAPTURE=ON \
  -DENABLE_IMGUR=OFF
cmake --build build-wayland-debug -j"$(nproc)"
tools/wayland-capture-debug.sh build-wayland-debug

What to include in an issue

LinScreen version and installation format.
Distribution, desktop and compositor versions.
Portal package and service list.
Monitor topology and scale factors.
Exact command, expected result and actual result.
Relevant logs with secrets removed.

Submit the report to the official tracker. See focused notes for GNOME and KDE Plasma.