Skip to content

"It doesn't work" Troubleshooting Checklist

Jump to bottom Edit New page
Aleksei Bavshin edited this page Jan 31, 2024 · 22 revisions

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. Or maybe you have a screencast that's stuck in the "paused" state, or some other problem.

This page contains a checklist to verify you've set up xdg-desktop-portal-wlr and the rest of the screensharing software stack correctly. If you want a more in-depth explanation of why things might not work out of the box look at systemd user services and environment page

  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 on demand.

  3. Is the Pipewire Multimedia Session Manager service running?

    One of:

    • systemctl --user status pipewire-media-session

    • systemctl --user status wireplumber

    ... should show active (running).

    If the service does not exist, your distro may package it as a separate package named something like pipewire-media-session or wireplumber + wireplumber-audio. Screencasts will be stuck in the "paused" state without a session manager.

    If you installed PipeWire just for the sake of xdpw, you may need to run systemctl --user enable pipewire-media-session so that it starts automatically when you log in. For wireplumber on some distros (such as OpenSUSE Tumbleweed), this isn't necessary since wireplumber.service has a WantedBy= relationship on pipewire.service by default, so check what your distro does.

  4. Is the xdp service running?

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

  5. 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 pipewire-media-session xdg-desktop-portal xdg-desktop-portal-wlr
systemctl --user start pipewire-media-session

    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. Replace pipewire-media-session with wireplumber if that's what you're using.

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

    • For sway, put them in a script that is execd from your sway config. Because the 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, add a new a0 = <command> (or another number if 0 is already taken) line under the [autostart] heading in your Wayfire config file, with <command> as the path to the script. If you prefer to use wcm, open it and add a new entry in the Autostart section with the path to the script.

    • For river, same as sway, you should put them on a separate script or you can put them on the last line of the overall config where it will be last executed.

  6. 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 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.

  7. Is the $compositor_name-portals.conf available in one of the locations documented in portals.conf(5)?

    xdg-desktop-portal 1.18 has switched to a new configuration format, where preferred portal implementations should be defined for each compositor in $compositor_name-portals.conf. Your distribution may already have included the configuration for your compositor, but if that's not the case, please create one in ~/.config/xdg-desktop-portal/$compositor_name-portals.conf. contrib/wlroots-portals.conf can be used as an example.

    Any entry in the XDG_CURRENT_DESKTOP can be used to find the portals.conf. E.g for XDG_CURRENT_DESKTOP=sway;wlroots xdp service will look for sway-portals.conf and wlroots-portals.conf and apply first available.

  8. Does the screencast starts, but the recording stays black or receives no image?

    Clients might not support the same format. Please run https://gist.github.com/columbarius/50239ea3c4c70df8f240aa50f88e801a and check if entries with "type": "PipeWire:Interface:Port" have the property .params.Format and if not check if .params.EnumFormat contains an entry compatible with the corresponding block from xdpw.

    Please add the output of the script when opening an issue.

Other known problems

"I tried setting the XDG_CURRENT_DESKTOP=$compositor_name but screensharing still does not work." Have you tried running your compositor with dbus-run-session? If you are using sway, try running it with XDG_CURRENT_DESKTOP=sway dbus-run-session sway. If you are using a display manager, edit /usr/share/wayland-sessions/sway.desktop like so:

[Desktop Entry]
Name=Sway
Comment=An i3-compatible Wayland compositor
Exec=env XDG_CURRENT_DESKTOP=sway dbus-run-session sway
Type=Application

In sway, make sure you did not set output HDMI-A-1 render_bit_depth 10. Screen capturing only works with 8-bit color space

Non-systemd distributions

runit

runit is a cross-platform Unix init scheme with service supervision, a replacement for sysvinit, and other init schemes. It runs on GNU/Linux, *BSD, MacOSX, Solaris, and can easily be adapted to other Unix operating systems. If runit runs for you on any other operating system, please let me know.

according to runit's website http://smarden.org/runit/

Issues in Void Linux

There is a chance that running pipewire and pipewire-pulse as a runit service daemon will not work with xdg-desktop-portal-wlr. Thus, you cannot start screencasting properly. The solution is instead of starting them as services, you should manually start pipewire and pipewire-pulse in your sway/river config. Additional configuration maybe required such as adding a config file on ~/.config/xdg-desktop-portal-wlr with the following lines:

[screencast]
output_name=eDP-1
max_fps=60
chooser_cmd=slurp -f %o -or
chooser_type=simple

There might be a need to add this line on the last line of the config of river and the beginning of the line of the config on sway:

exec dbus-update-activation-environment DISPLAY I3SOCK SWAYSOCK WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=$nameofcompositor

This will make dbus read your env vars properly and also xdg-desktop-portal-wlr to work.

Add a custom footer
Add a custom sidebar
Clone this wiki locally