Surviving Ubuntu 26.04 LTS: Fixing Qt 6 and ArcGIS Maps SDK for Qt on Wayland

The Upgrade Trap

If you are a Qt developer working with geospatial data, upgrading to Ubuntu 26.04 LTS (Resolute Raccoon) might have felt less like an upgrade and more like a system break.

We recently migrated our geospatial intelligence stack to the new LTS. Our goal was simple: run a Qt Quick application using the ArcGIS Maps SDK for Qt, powered by fine-tuned, edge-based geospatial agents for spatial grounding on satellite imagery.

Instead, we hit a brick wall. Here is the exact error we got when trying to run the standard Qt Online Installer:

./qt-online-installer-linux-x64-4.11.0.run: error while loading shared libraries: libxcb-icccm.so.4

What followed was a deep dive into the collision between Ubuntu's aggressive Wayland transition, Qt 6's new runtime dependencies, and missing X11 libraries. Here is how we fixed it, and how you can too.

The Root Cause: Wayland, XCB, and a Hidden Dependency

Ubuntu 26.04 defaults to Wayland. However, the ArcGIS Maps SDK for Qt relies heavily on OpenGL and historically has incomplete native Wayland support.

On some platforms things went from "rendering issues" to an immediate, hard crash.

To get our map rendering correctly, the standard workaround is to force the X11/XCB backend via XWayland using an environment variable:

export QT_QPA_PLATFORM=xcb

The issue is twofold:

1. Missing XCB Runtime Libraries: Ubuntu 26.04 no longer installs X11/XCB libraries by default. The Qt installer and the ArcGIS SDK need them.
2. Qt 6 Hard Dependency: Since Qt 6.5+, the xcb platform plugin has a hard runtime dependency on libxcb-cursor0. If this library is missing, the plugin fails to load, and Qt aborts the process immediately.

The Fix: A Step-by-Step Survival Guide

If you are developing Qt applications on Ubuntu 26.04, follow these steps to stabilize your environment.

Step 1: Install the Complete XCB Runtime Set

Don't just install libxcb-cursor0. Install the full suite of libraries that Qt and the ArcGIS SDK expect. This prevents you from playing "whack-a-mole" with missing dependencies.

sudo apt update
sudo apt install libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxcb-composite0

Step 2: Correctly Configure the Qt Platform Variable

If you are launching your app from a terminal or a script, ensure you use a comma, not a semicolon. For the ArcGIS SDK, forcing XCB is the most stable route:

# Force XCB backend for stable ArcGIS rendering
QT_QPA_PLATFORM=xcb ./YourGeospatialApp

If you want to try Wayland first and fall back to XCB, use a comma:

QT_QPA_PLATFORM=wayland,xcb ./YourGeospatialApp

Step 3: Check for Global Configuration Overrides

Some Ubuntu flavors set QT_QPA_PLATFORM globally. Check if your system is forcing a broken configuration:

grep -r "QT_QPA_PLATFORM" /etc/profile /etc/environment /etc/profile.d/

If you find a global setting with a semicolon (e.g., wayland;xcb), that is a bug you need to work around. Override it in your local shell profile (like ~/.bashrc or ~/.zshrc) using the correct comma syntax.

Step 4: Diagnose "Lying" Error Messages

If your app still crashes, Qt might be reporting a missing libxcb-cursor0 error when the actual missing library is something else entirely. Use ldd to find the real culprit:

ldd ./YourGeospatialApp | grep "not found"

The Payoff: Running Geospatial Intelligence on the Edge

After applying these fixes, our environment stabilized. We were able to run our HUD-styled Qt Quick prototype, successfully rendering satellite imagery of Frankfurt Airport via the ArcGIS Maps SDK.

Our prototype: A HUD-styled Qt Quick interface performing spatial grounding using edge-based geospatial agents on satellite imagery.

The combination of Qt 6, ArcGIS, and Ubuntu 26.04 is incredibly powerful for geospatial intelligence (GEOINT) once the environment is configured correctly. It allows us to run fine-tuned agents directly on the edge, processing high-resolution satellite imagery without relying on constant cloud connectivity.

Conclusion

Ubuntu 26.04 LTS is a solid release, but its aggressive move to Wayland has left the X11-dependent Qt ecosystem in a state of flux. By manually installing the XCB runtime libraries and correctly configuring the QT_QPA_PLATFORM variable, you can build a stable foundation for your geospatial applications.

Have you run into similar Wayland/X11 issues with Qt 6? Let me know in the comments.