{"record":{"id":"193aaff88c0e7519","repo":"unoplatform/uno","slug":"xlib-error-cannot-connect-to-x-server","errorCode":null,"errorMessage":"XLIB ERROR: Cannot connect to X server","messagePattern":"XLIB ERROR: Cannot connect to X server","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"src/AddIns/Uno.UI.MediaPlayer.Skia.X11/X11MediaPlayerPresenterExtension.cs","lineNumber":36,"sourceCode":"{\n\tprivate readonly MediaPlayerPresenter _presenter;\n\tprivate SharedMediaPlayerExtension? _playerExtension;\n\tprivate readonly X11Window _x11Window;\n\n\tpublic X11MediaPlayerPresenterExtension(MediaPlayerPresenter presenter)\n\t{\n\t\t_presenter = presenter;\n\n\t\tIntPtr display = XLib.XOpenDisplay(IntPtr.Zero);\n\t\tusing var lockDisposable = X11Helper.XLock(display);\n\n\t\tif (display == IntPtr.Zero)\n\t\t{\n\t\t\tif (this.Log().IsEnabled(Microsoft.Extensions.Logging.LogLevel.Error))\n\t\t\t{\n\t\t\t\tthis.Log().Error(\"XLIB ERROR: Cannot connect to X server\");\n\t\t\t}\n\t\t\tthrow new InvalidOperationException(\"XLIB ERROR: Cannot connect to X server\");\n\t\t}\n\n\t\tint screen = XLib.XDefaultScreen(display);\n\n\t\t_ = XLib.XFlush(display); // unnecessary on most Xlib implementations\n\n\t\tif (this.Log().IsEnabled(Microsoft.Extensions.Logging.LogLevel.Trace))\n\t\t{\n\t\t\tthis.Log().Trace(\"Created media player window.\");\n\t\t}\n\n\t\t_x11Window = new X11Window(display, XLib.XCreateSimpleWindow(\n\t\t\tdisplay,\n\t\t\tXLib.XRootWindow(display, screen),\n\t\t\t0,\n\t\t\t0,\n\t\t\t1,\n\t\t\t1,","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/unoplatform/uno/blob/04183404888ea21b4e5bfa3493e8d5f15e972c3a/src/AddIns/Uno.UI.MediaPlayer.Skia.X11/X11MediaPlayerPresenterExtension.cs#L18-L54","documentation":"InvalidOperationException thrown by X11MediaPlayerPresenterExtension's constructor when XLib.XOpenDisplay(IntPtr.Zero) returns IntPtr.Zero, meaning no X server connection could be established. On the Skia/X11 target, the media player extension needs its own X display to host the LibVLC window. Without a display, native video hosting is impossible.","triggerScenarios":"Constructing X11MediaPlayerPresenterExtension (media playback on Skia Linux/X11) when DISPLAY is unset or points to an unreachable/non-existent X server; running headless (no X server, no Xvfb); SSH session without X forwarding; Wayland-only session without XWayland.","commonSituations":"CI/containers running the Skia X11 app without Xvfb; misconfigured DISPLAY=:0 on a headless server; Wayland environment where XWayland isn't available; SSH without -X; a systemd service without display access. The error is also logged before throwing.","solutions":["Set DISPLAY correctly (export DISPLAY=:0) and ensure an X server is running.","In headless/CI, run under Xvfb: xvfb-run ./app or start Xvfb and point DISPLAY to it.","On Wayland, ensure XWayland is installed and enabled.","For SSH, use ssh -X (or -Y) to forward X11, or run locally.","If media playback isn't needed, avoid instantiating MediaPlayerPresenter on X11; guard behind a capability check."],"exampleFix":"# before — headless run\n./MyUnoApp\n\n# after — provide a virtual X server\nxvfb-run -a ./MyUnoApp\n# or\nXvfb :99 & export DISPLAY=:99 && ./MyUnoApp","handlingStrategy":"validation","validationCode":"// Verify an X display is reachable before constructing the X11 media extension\nif (Environment.GetEnvironmentVariable(\"DISPLAY\") is { } d && XLib.XOpenDisplay(IntPtr.Zero) != IntPtr.Zero)\n    _presenter = new X11MediaPlayerPresenterExtension(mediaPresenter);\nelse\n    Log.Error(\"No X server available; set DISPLAY or run under Xvfb.\");","typeGuard":"bool XServerAvailable()\n    => Environment.GetEnvironmentVariable(\"DISPLAY\") is not null\n       && XLib.XOpenDisplay(IntPtr.Zero) != IntPtr.Zero;","tryCatchPattern":"try { _presenter = new X11MediaPlayerPresenterExtension(mediaPresenter); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Cannot connect to X server\"))\n{ Log.Error(\"X11 unavailable — install/run Xvfb or set DISPLAY.\"); }","preventionTips":["Set DISPLAY and run an X server (or Xvfb) on Linux/CI.","Ensure XWayland is available on Wayland-only systems.","Use xvfb-run in headless CI.","Guard media playback behind an X-availability check."],"tags":["x11","media-player","libvlc","skia","linux","display","uno-platform"],"backgroundTag":null,"analyzedSha":"04183404888ea21b4e5bfa3493e8d5f15e972c3a","analyzedAt":"2026-08-13T21:08:11.651Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}