Yalantis/uCrop · error · CImgDisplayException

CImgDisplay::assign(): Failed to open X11 display.

Error message

CImgDisplay::assign(): Failed to open X11 display.

What it means

CImgDisplay::assign() on X11 builds throws CImgDisplayException when XOpenDisplay(NULL) returns NULL, i.e. a connection to the X server could not be established. This means the DISPLAY environment points nowhere or X authorization failed, so no window can be created.

Source

Thrown at ucrop/src/main/jni/CImg.h:10041

      if (!_keys) _keys = new unsigned int[128];
      if (!_released_keys) _released_keys = new unsigned int[128];

      // Allocate space for window title.
      const char *const np_title = p_title?p_title:"";
      const unsigned int s = (unsigned int)std::strlen(np_title) + 1;
      char *const tmp_title = s?new char[s]:0;
      if (s) std::memcpy(tmp_title,np_title,s*sizeof(char));

      // Destroy previous display window if existing.
      if (!is_empty()) assign(false);

      // Open X11 display and retrieve graphical properties.
      cimg::X11_attr &X11_attr = cimg::X11_attr::ref();
      Display* &dpy = X11_attr.display;
      if (!dpy) {
        dpy = XOpenDisplay(0);
        if (!dpy)
          throw CImgDisplayException(_cimgdisplay_instance
                                     "assign(): Failed to open X11 display.",
                                     cimgdisplay_instance);

        X11_attr.nb_bits = DefaultDepth(dpy,DefaultScreen(dpy));
        if (X11_attr.nb_bits!=8 && X11_attr.nb_bits!=16 &&
            X11_attr.nb_bits!=24 && X11_attr.nb_bits!=32)
          throw CImgDisplayException(_cimgdisplay_instance
                                     "assign(): Invalid %u bits screen mode detected "
                                     "(only 8, 16, 24 and 32 bits modes are managed).",
                                     cimgdisplay_instance,
                                     X11_attr.nb_bits);
        XVisualInfo vtemplate;
        vtemplate.visualid = XVisualIDFromVisual(DefaultVisual(dpy,DefaultScreen(dpy)));
        int nb_visuals;
        XVisualInfo *vinfo = XGetVisualInfo(dpy,VisualIDMask,&vtemplate,&nb_visuals);
        if (vinfo && vinfo->red_mask<vinfo->blue_mask) X11_attr.is_blue_first = true;
        X11_attr.byte_order = ImageByteOrder(dpy);
        XFree(vinfo);

View on GitHub (pinned to f788b534b4)

Solutions

1. Set DISPLAY correctly (e.g. export DISPLAY=:0) and confirm the X server is reachable
2. Use SSH with X forwarding (ssh -X/-Y) or run inside an existing X session
3. Install/start Xvfb for headless/CI: Xvfb :99 & export DISPLAY=:99
4. Check Xauthority: ensure ~/.Xauthority matches and you are authorized on the server

Example fix

// before
cimg::CImgDisplay disp(width, height, "win"); // fails headless
// after (CI/headless shell)
Xvfb :99 -screen 0 1280x1024x24 &
export DISPLAY=:99
cimg::CImgDisplay disp(width, height, "win");

const char *d = getenv("DISPLAY");
bool xReady = d && *d && (system("xset -q > /dev/null 2>&1") == 0); // probe before creating display

bool canOpenX11() { const char *d = getenv("DISPLAY"); return d && *d; }

try { cimg::CImgDisplay d(w, h, "win"); } catch (const cimg_library::CImgDisplayException &e) { fprintf(stderr, "No X display: %s\n", e.what()); exit(1); }

When it happens

Trigger: Calling CImgDisplay::assign() (or the CImgDisplay constructor) in an environment with no X server: DISPLAY unset, SSH without X forwarding, headless CI, Wayland-only session without XWayland, or X server not running.

Common situations: Running tests or the app inside a Docker container/CI without X11; SSH session without -X/-Y forwarding; DISPLAY lost after su/sudo or cron/systemd service context; Android/headless server builds.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• CImgDisplay::screen_width(): Failed to open X11 display.
• CImgDisplay(): No display available.
• CImgDisplay::assign(): Invalid %u bits screen mode detected
• CImgDisplay::assign(): Max number of displays (512) already
• init_fullscreen(): Xrandr extension not supported by the X s

AI-assisted analysis of Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/49c0b0799c99ce70. Report an issue: GitHub.