"It doesn't work" Troubleshooting Checklist

You tried to screen-share and got either a completely black window, or a composite of all your Xwayland windows. This indicates the screensharer is falling back to X11 screensharing instead of using the xdg-desktop-portal screensharing stack.

This page contains a checklist to verify you've set up xdg-desktop-portal-wlr and the rest of the screensharing software stack correctly.

1. Does the screen-sharing application support PipeWire for screen-sharing?

   For Firefox and Chromium, upstream's binaries link to the PipeWire 0.2 client library, whereas your actual PipeWire service is likely to be 0.3. Alternatively, some distros patch Firefox and/or Chromium to use PipeWire 0.3 directly. In the former case, check if your distro has a package for the PipeWire compat client library; this library allows programs to use the 0.2 client API to talk to the 0.3 service.

   For Firefox, ensure the media.peerconnection.enabled flag in about:config is set to true and not false.

   For Chromium, ensure the WebRTC PipeWire support flag at chrome://flags/#enable-webrtc-pipewire-capturer is set to Enabled.

2. Is the PipeWire service running?

   systemctl --user status pipewire.socket pipewire should show active (running) for both.

   If you installed PipeWire just for the sake of xdpw, make sure to run systemctl --user enable pipewire.socket so that it starts automatically when you log in.

3. Is the xdp service running?

   systemctl --user status xdg-desktop-portal should show active (running).

4. Does the xdp service know your wayland socket?

   env | grep '^WAYLAND_DISPLAY=' will show the value of the WAYLAND_DISPLAY environment variable set by your Wayland compositor.

   < "/proc/$(pidof xdg-desktop-portal)/environ" tr '\0' '\n' | grep '^WAYLAND_DISPLAY=' should print the same value. If it does not print anything, run:

   # Import the WAYLAND_DISPLAY env var from sway into the systemd user session.
   dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
   
   # Stop any services that are running, so that they receive the new env var when they restart.
   systemctl --user stop pipewire xdg-desktop-portal xdg-desktop-portal-wlr

   For sway, you can put those two commands in a script that is execd from your sway config. Because the two commands must run in sequence, you should put them in a script rather than execing them individually, since sway runs execd commands in parallel.

5. Does the xdp service know what your desktop is?

   < "/proc/$(pidof xdg-desktop-portal)/environ" tr '\0' '\n' | grep '^XDG_CURRENT_DESKTOP=' should print XDG_CURRENT_DESKTOP=sway. If it does not, running the two commands suggested in the previous list item will handle it.

   If multiple portals are installed (GNOME, KDE, etc), the xdp service looks at the XDG_CURRENT_DESKTOP env var to know which portal to use. Just like the WAYLAND_DISPLAY env var above, this env var needs to be defined on the xdp service. Technically this is only necessary if you have multiple portals installed, but it's a good idea to set it anyway.

   It's also a good idea to define XDG_CURRENT_DESKTOP=sway in the shell that you used to start sway, because some applications also benefit from having the env var set.