From 6f7d1e0b2b351753548e0b563c4b47a6d5783832 Mon Sep 17 00:00:00 2001 From: Bernardo Gomes Date: Sat, 29 Nov 2025 03:07:18 -0300 Subject: [PATCH] docs: add Wayland troubleshooting guide for Linux users Add comprehensive troubleshooting section for Wayland display server issues on Linux. This addresses common crashes and initialization failures experienced by users on Wayland compositors (Hyprland, Sway, KDE Plasma, GNOME). The guide provides two workarounds to force X11/XWayland backend: - Environment variable method (ELECTRON_OZONE_PLATFORM_HINT) - Command line flag method (--ozone-platform=x11) References: - Fixes #2759 - Related to #2107 --- docs/advanced-usage.md | 50 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index a21dad1a1..236ba289d 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -66,3 +66,53 @@ If you later decide you would like to remove a 3rd party theme you installed, it 1. If Arduino IDE is running, select **File > Quit** from the Arduino IDE menus to exit all windows. 1. Delete the theme's `.vsix` file from [the location you installed it to](#installation).
⚠ Please be careful when deleting things from your computer. When in doubt, back up! + +## Troubleshooting + +### Linux: Wayland Display Server Issues + +Arduino IDE is built on [Electron](https://www.electronjs.org/), which attempts to use native Wayland rendering on Linux systems with Wayland display servers. However, some Wayland compositors (particularly Hyprland, Sway, and some configurations of KDE Plasma and GNOME) may experience crashes or initialization failures with errors such as: + +``` +Failed to connect to Wayland display +Failed to initialize Wayland platform +The platform failed to initialize. Exiting. +``` + +Or segmentation faults immediately after launching. + +#### Workaround: Force X11/XWayland Backend + +If you encounter Wayland-related crashes, you can force Arduino IDE to use the X11/XWayland backend instead of native Wayland rendering: + +**Method 1: Environment Variable (Recommended)** + +Set the `ELECTRON_OZONE_PLATFORM_HINT` environment variable before launching Arduino IDE: + +```bash +export ELECTRON_OZONE_PLATFORM_HINT=x11 +arduino-ide +``` + +To make this permanent, add the export line to your shell configuration file (`~/.bashrc`, `~/.zshrc`, or equivalent). + +**Method 2: Command Line Flag** + +Launch Arduino IDE with the `--ozone-platform=x11` flag: + +```bash +arduino-ide --ozone-platform=x11 +``` + +You can create a wrapper script or shell alias for convenience: + +```bash +# Add to ~/.bashrc or ~/.zshrc +alias arduino-ide='arduino-ide --ozone-platform=x11' +``` + +#### Related Issues + +For more information and updates on native Wayland support, see: +- [Issue #2759: Segmentation fault when launching Arduino IDE](https://github.com/arduino/arduino-ide/issues/2759) +- [Issue #2107: IDE crashes with segmentation fault when run under native Wayland](https://github.com/arduino/arduino-ide/issues/2107)