From 9ee8a53b9c89df580742f20e0834a4b872e54788 Mon Sep 17 00:00:00 2001
From: deepend <deepend@tilde.club>
Date: Tue, 24 Feb 2026 11:48:04 -0700
Subject: [PATCH] Moved the Flatpak display troubleshooting content from
 readme.md into a standalone troubleshooting.md document, as requested.

Replaced the large inline README section with a single link to the new troubleshooting file to keep the README concise.
---
 readme.md          |  3 +++
 troubleshooting.md | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 troubleshooting.md

diff --git a/readme.md b/readme.md
index c74fea04..f1c06092 100644
--- a/readme.md
+++ b/readme.md
@@ -36,6 +36,9 @@ See [IRCHelp.org](http://irchelp.org) for information about IRC in general.
 For more information on ZoiteChat please read our [documentation](https://docs.zoitechat.zoite.net/):
 - [Downloads](https://zoitechat.zoite.net/download)
 
+- [Troubleshooting](troubleshooting.md)
+
+
 ---
 
 <sub>
diff --git a/troubleshooting.md b/troubleshooting.md
new file mode 100644
index 00000000..23cf8c51
--- /dev/null
+++ b/troubleshooting.md
@@ -0,0 +1,41 @@
+# Troubleshooting
+
+## Flatpak
+
+If `flatpak run net.zoite.Zoitechat` only prints `Gtk-WARNING **: cannot open display`,
+collect extra diagnostics with:
+
+```bash
+flatpak run --devel --command=sh net.zoite.Zoitechat
+```
+
+Then inside that shell:
+
+```bash
+echo "DISPLAY=$DISPLAY WAYLAND_DISPLAY=$WAYLAND_DISPLAY XDG_SESSION_TYPE=$XDG_SESSION_TYPE"
+xdpyinfo >/tmp/xdpyinfo.log 2>&1 || true
+env G_MESSAGES_DEBUG=all zoitechat 2>&1 | tee /tmp/zoitechat-debug.log
+```
+
+To inspect sandbox permissions from the host:
+
+```bash
+flatpak info --show-permissions net.zoite.Zoitechat
+flatpak override --user --show net.zoite.Zoitechat
+```
+
+If needed, try running with direct access to your active display stack:
+
+```bash
+# X11 sessions
+flatpak override --user --socket=x11 net.zoite.Zoitechat
+
+# Wayland sessions
+flatpak override --user --socket=wayland net.zoite.Zoitechat
+```
+
+You can reset overrides after testing:
+
+```bash
+flatpak override --user --reset net.zoite.Zoitechat
+```