How do I correctly configure display settings for my GTK app on Ubuntu?

by

Summary

This postmortem analyzes why a GTK application fails with “Failed to open display” when launched under GAS (Gtk Application Server) on Ubuntu, even though other GTK apps (like gedit) work correctly. The issue stems from missing Broadway display initialization, environment mismatches, and incorrect display backend assumptions inside the custom application.

Root Cause

The root cause is that the custom GTK app is not initializing the Broadway backend, while gedit and other system GTK apps correctly fall back to Broadway when run under GAS.

Key contributing factors include:

  • DISPLAY and GDK_BACKEND not set for the custom app in the GAS execution environment
  • GTK cannot auto-detect Broadway unless the app is launched with the correct backend variables
  • gedit is patched/compiled with broader backend support, while the custom app is not
  • Broadway requires explicit configuration when running headless over SSH

Why This Happens in Real Systems

Real-world GTK deployments often fail in headless or remote environments because:

  • GTK apps assume X11 or Wayland unless explicitly told otherwise
  • System apps (like gedit) include fallback logic that custom apps lack
  • Broadway is a non-default backend, so apps must be configured to use it
  • GAS spawns apps in a clean environment, so missing variables break display initialization
  • SSH sessions often override or unset display-related environment variables

Real-World Impact

When Broadway is not correctly configured:

  • Apps fail with “Failed to open display” instead of “cannot open display”, indicating backend mismatch
  • GAS spawns the app but cannot attach a Broadway display socket
  • Users see a blank or failed session in the browser
  • Debugging becomes difficult because GTK error messages are inconsistent across apps
  • Production systems experience silent failures when GUI apps are launched headlessly

Example or Code (if necessary and relevant)

A minimal Broadway-compatible launch environment typically requires:

export GDK_BACKEND=broadway
export BROADWAY_DISPLAY=:5
broadwayd :5 &
./your-app

This ensures GTK initializes the Broadway backend instead of X11/Wayland.

How Senior Engineers Fix It

Experienced engineers resolve this by ensuring the runtime environment is correct rather than modifying the app itself.

Typical fixes include:

  • Setting GDK_BACKEND=broadway in the GAS service unit
  • Ensuring BROADWAY_DISPLAY is unique per session
  • Verifying that broadwayd is running before the app starts
  • Checking that the app is linked against GTK4 with Broadway support enabled
  • Using systemd Environment= directives to enforce consistent display variables
  • Testing the app under a clean shell to reproduce GAS’s environment

They also validate that:

  • The app does not hardcode X11-only APIs
  • The app does not require Wayland-specific features
  • The app can run headlessly without a compositor

Why Juniors Miss It

Less experienced engineers often overlook this issue because:

  • They assume GTK automatically selects the correct backend
  • They test locally on a desktop environment where X11/Wayland is always available
  • They do not inspect environment variables inside systemd services
  • They misinterpret the difference between
    • “cannot open display” (X11 failure)
    • “Failed to open display” (no backend available at all)
  • They expect GAS to “just work” without understanding GTK backend mechanics
  • They do not realize that Broadway is opt‑in, not automatic

The subtle difference in error messages leads juniors to chase the wrong problem, while seniors recognize it as a backend initialization failure rather than a GAS bug.

Leave a Comment