diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index f59b7ef213f..55495d04544 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -128,6 +128,27 @@ resort suggestion.
 
 ## Linux
 
+### Hardware Encoders throttle/drop FPS during high GPU load
+Capture methods (`wlgrab`) or encoders (`nvenc`, `vaapi`) that utilize EGL contexts may exhibit FPS drops
+in conjunction with a Sunshine installation that runs in a sandboxed or reduced permissions state
+(Flatpak, AppImage, or when using Portal capture) due to the lack of active CAP_SYS_NICE process permissions
+needed to set up high priority EGL contexts.
+
+To check if you are affected by this issue, look out for this message in your Sunshine log:
+```
+Warning: EGL: context priority set to HIGH but CAP_SYS_NICE capability is missing
+```
+
+> [!IMPORTANT]
+> Switching to Vulkan encoding should resolve the issue for the majority of configurations, but refer to this
+> table for recommended configurations (especially if Vulkan encoding is not supported on your system):
+> | Desktop Environment | Vulkan Supported? | Recommended Sunshine Install Type | Recommended Capture & Encoder Configuration       |
+> |:--------------------|-------------------|-----------------------------------|--------------------------------------------------:|
+> | KDE Plasma          | Yes               | Any                               | `portal` or `kwin` capture with `vulkan` encoding |
+> | KDE Plasma          | No                | Non-Sandboxed                     | `kwin` capture with `vaapi`/`nvenc` encoding      |
+> | GNOME / other       | Yes               | Any                               | `portal` capture with `vulkan` encoding           |
+> | GNOME / other       | No                | Non-Sandboxed                     | `kms` capture with `vaapi`/`nvenc` encoding       |
+
 ### Hardware Encoding fails
 Due to legal concerns, Mesa has disabled hardware decoding and encoding by default.
 
@@ -149,6 +170,20 @@ If you see the above error in the Sunshine logs, compiling *Mesa* manually may b
 > Other build options are listed in the
 > [meson options](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/meson_options.txt) file.
 
+### Portal token issues
+Portal capture requires you to manually approve Remote Desktop permissions via an on-screen prompt on the host.
+This creates a portal token which is used to automaticaly reauthorize on subsequent reconnects, but under certain
+circumstances (a Sunshine crash, switching to another desktop environment, or if a monitor hotplug event occurs)
+the portal token may become lost or invalid, necessitating manual re-approval of capture permissions.
+
+Users of the KDE Plasma desktop can bypass this issue either by switching to `kwin` capture or setting the following
+configuration to enable permanent capture autorization for Sunshine via Portal capture:
+```
+flatpak permission-set kde-authorized remote-desktop dev.lizardbyte.app.Sunshine yes
+```
+> [!NOTE]
+> Although this configuration is plumbed through Flatpak, it will work with any supported Sunshine installation type.
+
 ### Input not working
 After installation, the `udev` rules need to be reloaded. Our post-install script tries to do this for you
 automatically, but if it fails, you may need to restart your system.