claudetools/docs/forum-posts/screenconnect-linux-wayland-fix.md

# Fix: ConnectWise ScreenConnect Client on Arch Linux with Wayland

## Environment
- OS: CachyOS (Arch-based), kernel 6.19.x
- DE: KDE Plasma 6 (Wayland session)
- Java: OpenJDK 25.x
- ScreenConnect: Access Host client (Linux .sh installer)

## Problem

The ScreenConnect `.sh` installer fails on Arch Linux because it only supports `dpkg` (Debian) and `rpm` (Red Hat) package managers. Even after getting it installed, the client connects but produces no visible window on Wayland desktops.

There are three separate issues that must be fixed in sequence.

## Issue 1: Installer Doesn't Work on Arch

The `ScreenConnect.ClientSetup.sh` installer checks for `dpkg` or `rpm`, neither of which exist on Arch by default. The script contains two embedded installers — "Guest" (uses package managers) and "Host" (self-contained tar.gz). The Guest installer's `exit 0` at line ~557 prevents the Host installer from running if a package manager isn't found.

**Fix:** Install `dpkg` so the installer's detection logic succeeds:
```bash
sudo pacman -S dpkg
```

Then run the installer **as your regular user** (not root):
```bash
~/Downloads/ScreenConnect.ClientSetup.sh
```

**Gotcha:** If you run with `sudo`, it installs to `/root/.local/share/applications/` instead of your home directory. To fix this:
```bash
sudo mv /root/.local/share/applications/connectwisecontrol-* ~/.local/share/applications/
sudo chown -R $USER:$USER ~/.local/share/applications/connectwisecontrol-*
```

The installed location is: `~/.local/share/applications/connectwisecontrol-<hash>/`

### Alternative: PKGBUILD Approach

There's a [community PKGBUILD on GitHub](https://github.com/kelderek/connectwisecontrol-arch) that repackages the `.deb` as a proper Arch package with a systemd service. This is a good option if you want pacman-managed installs and `pacman -Rs` uninstallation. However, the simpler `dpkg` approach above works well for the Access Host client.

## Issue 2: Java Headless — No GUI Support

The ScreenConnect client is a Java Swing application. CachyOS (and many Arch installs) ships `jre-openjdk-headless` by default, which lacks AWT/Swing libraries.

**Error in logs** (`~/.local/share/applications/connectwisecontrol-<hash>-logs`):
```
java.awt.HeadlessException:
No X11 DISPLAY variable was set,
or no headful library support was found
```

**Fix:** Install the full (headful) JRE:
```bash
sudo pacman -S --ask 4 jre-openjdk
# --ask 4 allows replacing the conflicting headless package
```

## Issue 3: Wayland Incompatibility

Java AWT/Swing does not support Wayland natively. Even with the full JRE, the ScreenConnect window fails to create on a Wayland session because the Java toolkit can't open an X11 display.

**Error in logs:**
```
java.lang.NullPointerException: Cannot invoke "com.screenconnect.client.ScreenFrame.getScreenPanel()"
because "this.screenFrame" is null
```

**Fix:** Force X11 (XWayland) backend by patching the launcher script:
```bash
sed -i '1a export GDK_BACKEND=x11\nexport _JAVA_AWT_WM_NONREPARENTING=1' \
  ~/.local/share/applications/connectwisecontrol-*/ClientLauncher.sh
```

- `GDK_BACKEND=x11` forces the Java process to use XWayland instead of native Wayland
- `_JAVA_AWT_WM_NONREPARENTING=1` is recommended by the Arch `jre-openjdk` package for tiling/non-reparenting window managers, and fixes rendering issues on KDE Plasma under Wayland

## Autostart on Login

To have ScreenConnect start automatically when you log in, copy the `.desktop` file to your autostart directory:
```bash
cp ~/.local/share/applications/connectwisecontrol-*.desktop ~/.config/autostart/
```

## Complete Setup (TL;DR)

```bash
# 1. Install dependencies
sudo pacman -S dpkg jre-openjdk

# 2. Run installer as your user (NOT sudo)
~/Downloads/ScreenConnect.ClientSetup.sh

# 3. Patch launcher for Wayland
sed -i '1a export GDK_BACKEND=x11\nexport _JAVA_AWT_WM_NONREPARENTING=1' \
  ~/.local/share/applications/connectwisecontrol-*/ClientLauncher.sh

# 4. Enable autostart
cp ~/.local/share/applications/connectwisecontrol-*.desktop ~/.config/autostart/

# 5. Launch
sh ~/.local/share/applications/connectwisecontrol-*/ClientLauncher.sh
```

## Verification

Check the log file for errors:
```bash
cat ~/.local/share/applications/connectwisecontrol-*-logs
```

A clean run should show only these non-fatal warnings:
```
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::loadLibrary has been called by com.screenconnect.Extensions
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning
WARNING: Restricted methods will be blocked in a future release unless native access is enabled
```

## Important Notes

- **Updates overwrite the patch.** The `ClientLauncher.sh` Wayland fix will be lost if ScreenConnect updates itself or you reinstall. Reapply the `sed` command after any update.
- **Logs location:** `~/.local/share/applications/connectwisecontrol-<hash>-logs`
- **Desktop entry:** `~/.local/share/applications/connectwisecontrol-<hash>.desktop`
- **Applies to all Arch-based distros** on Wayland: CachyOS, Manjaro, EndeavourOS, etc.
- **Applies to all Wayland compositors:** KDE Plasma, GNOME, Sway, Hyprland, etc.

## What Doesn't Work (Online Suggestions to Avoid)

- **IcedTea / Java Web Start (JNLP):** Frequently recommended in forums but broken with modern Java versions. Only works for the web viewer, not the persistent Access Host agent.
- **Switching to X11 globally:** Works, but defeats the purpose of running Wayland. The per-app `GDK_BACKEND=x11` fix is better.
- **Debtap:** Can convert the `.deb` but doesn't create a systemd service or handle the Wayland issue. More steps for the same result.