"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. If this is the case for you, 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. Alternatively, some distros patch Firefox and/or Chromium to use PipeWire 0.3 directly. Check this table for what your distro does.

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

   For Chromium, also 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=$compositor_name
   
   # 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

   Replace the "$compositor_name" in XDG_CURRENT_DESKTOP=$compositor_name with the name of your compositor, according to what it's called in the UseIn= line of /usr/share/xdg-desktop-portal/portals/wlr.portal. That is, XDG_CURRENT_DESKTOP=sway for sway, XDG_CURRENT_DESKTOP=Wayfire for wayfire, and XDG_CURRENT_DESKTOP=river for river.

   You should use your compositor's method for autostart commands to run those two commands when the compositor starts:

   • For sway, put them 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 individual exec'd commands in parallel.

   • For Wayfire, TODO EDIT ME IF YOU KNOW HOW.

   • For river, TODO EDIT ME IF YOU KNOW HOW.

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

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

   If multiple portals are installed (GNOME, KDE, xdpw, 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=$compositor_name in the shell that you used to start your compositor, because some applications also benefit from having the env var set.

6. Is pipewire-media-session available as a separate package in your distribution? Some distributions (like Arch) have a separate package for it. Screencasts will be stuck in the "paused" state without a session manager.