{"record":{"id":"49c0b0799c99ce70","repo":"Yalantis/uCrop","slug":"cimgdisplay-assign-failed-to-open-x11-display","errorCode":null,"errorMessage":"CImgDisplay::assign(): Failed to open X11 display.","messagePattern":"CImgDisplay::assign\\(\\): Failed to open X11 display\\.","errorType":"exception","errorClass":"CImgDisplayException","httpStatus":null,"severity":"error","filePath":"ucrop/src/main/jni/CImg.h","lineNumber":10041,"sourceCode":"      if (!_keys) _keys = new unsigned int[128];\n      if (!_released_keys) _released_keys = new unsigned int[128];\n\n      // Allocate space for window title.\n      const char *const np_title = p_title?p_title:\"\";\n      const unsigned int s = (unsigned int)std::strlen(np_title) + 1;\n      char *const tmp_title = s?new char[s]:0;\n      if (s) std::memcpy(tmp_title,np_title,s*sizeof(char));\n\n      // Destroy previous display window if existing.\n      if (!is_empty()) assign(false);\n\n      // Open X11 display and retrieve graphical properties.\n      cimg::X11_attr &X11_attr = cimg::X11_attr::ref();\n      Display* &dpy = X11_attr.display;\n      if (!dpy) {\n        dpy = XOpenDisplay(0);\n        if (!dpy)\n          throw CImgDisplayException(_cimgdisplay_instance\n                                     \"assign(): Failed to open X11 display.\",\n                                     cimgdisplay_instance);\n\n        X11_attr.nb_bits = DefaultDepth(dpy,DefaultScreen(dpy));\n        if (X11_attr.nb_bits!=8 && X11_attr.nb_bits!=16 &&\n            X11_attr.nb_bits!=24 && X11_attr.nb_bits!=32)\n          throw CImgDisplayException(_cimgdisplay_instance\n                                     \"assign(): Invalid %u bits screen mode detected \"\n                                     \"(only 8, 16, 24 and 32 bits modes are managed).\",\n                                     cimgdisplay_instance,\n                                     X11_attr.nb_bits);\n        XVisualInfo vtemplate;\n        vtemplate.visualid = XVisualIDFromVisual(DefaultVisual(dpy,DefaultScreen(dpy)));\n        int nb_visuals;\n        XVisualInfo *vinfo = XGetVisualInfo(dpy,VisualIDMask,&vtemplate,&nb_visuals);\n        if (vinfo && vinfo->red_mask<vinfo->blue_mask) X11_attr.is_blue_first = true;\n        X11_attr.byte_order = ImageByteOrder(dpy);\n        XFree(vinfo);","sourceCodeStart":10023,"sourceCodeEnd":10059,"githubUrl":"https://github.com/Yalantis/uCrop/blob/f788b534b48c144edf786c8cddbf0e029e637804/ucrop/src/main/jni/CImg.h#L10023-L10059","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set DISPLAY correctly (e.g. export DISPLAY=:0) and confirm the X server is reachable","Use SSH with X forwarding (ssh -X/-Y) or run inside an existing X session","Install/start Xvfb for headless/CI: Xvfb :99 & export DISPLAY=:99","Check Xauthority: ensure ~/.Xauthority matches and you are authorized on the server"],"exampleFix":"// before\ncimg::CImgDisplay disp(width, height, \"win\"); // fails headless\n// after (CI/headless shell)\nXvfb :99 -screen 0 1280x1024x24 &\nexport DISPLAY=:99\ncimg::CImgDisplay disp(width, height, \"win\");","handlingStrategy":"try-catch","validationCode":"const char *d = getenv(\"DISPLAY\");\nbool xReady = d && *d && (system(\"xset -q > /dev/null 2>&1\") == 0); // probe before creating display","typeGuard":"bool canOpenX11() { const char *d = getenv(\"DISPLAY\"); return d && *d; }","tryCatchPattern":"try { cimg::CImgDisplay d(w, h, \"win\"); } catch (const cimg_library::CImgDisplayException &e) { fprintf(stderr, \"No X display: %s\\n\", e.what()); exit(1); }","preventionTips":["Always set/verify DISPLAY in deployment scripts, containers, and CI","Use Xvfb for headless automated runs","Enable X forwarding (ssh -X/-Y) for remote GUI usage","On Wayland, ensure XWayland is running since CImg uses X11 directly"],"tags":["x11","display","environment","headless"],"backgroundTag":"missing-env-var","analyzedSha":"f788b534b48c144edf786c8cddbf0e029e637804","analyzedAt":"2026-09-08T08:36:04.887Z","contentChangedAt":"2026-09-08T08:36:04.887Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}