Skip to main content
This page addresses graphics-related errors you may encounter when running graphical applications in the Raylib Container.

​
Display Connection Errors

Error Message:
cannot open display: :0
Cause:This error occurs when the container cannot connect to your host system’s graphics server (X11 or Wayland via XWayland). Common causes include:
  • The xhost +local:docker command wasn’t run
  • The DISPLAY environment variable isn’t being passed correctly
  • X11 socket isn’t mounted properly
Solutions:
1

Grant Display Access

Allow Docker containers to connect to your graphics server:
xhost +local:docker
This command needs to be run in each new graphical session or after rebooting the system.
2

Verify DISPLAY Variable

Ensure the DISPLAY environment variable is set on your host:
echo $DISPLAY
This should output something like :0 or :1.
3

Check Docker Run Command

Verify your docker run command includes these parameters:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    raylib_container
  • -e DISPLAY=$DISPLAY passes the host’s DISPLAY variable to the container
  • -v /tmp/.X11-unix:/tmp/.X11-unix mounts the X11 socket
4

Test Graphics Connection

Once inside the container, test the graphics connection:
xeyes
A window with eyes that follow the mouse should appear.

​
Hardware Acceleration Errors

Error Message:
MESA: error: Failed to query drm device.
Cause:This error indicates that the container cannot access your GPU’s Direct Rendering Infrastructure (DRI) devices. Hardware acceleration is not working.Solutions:
1

Verify DRI Device Flag

Ensure your docker run command includes the --device flag:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    --device /dev/dri:/dev/dri \
    raylib_container
The --device /dev/dri:/dev/dri flag maps the host’s Direct Rendering Infrastructure devices into the container.
2

Check DRI Devices Exist

Verify DRI devices exist on your host:
ls -l /dev/dri/
You should see devices like card0, renderD128, etc.
3

Fallback to Software Rendering

If hardware acceleration still doesn’t work, use software rendering:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v ./user_code:/app/user_code \
    -e LIBGL_ALWAYS_SOFTWARE=1 \
    raylib_container
Performance will be lower with software rendering, but it works as a reliable fallback.
Error Message:
glx: failed to create dri3 screen
Cause:This error occurs when GLX (OpenGL Extension to the X Window System) cannot initialize DRI3 for hardware-accelerated rendering. This is a hardware acceleration issue.Solution:
1

Ensure DRI Device Access

Make sure you’re using the --device /dev/dri:/dev/dri flag:
docker run -it --rm \
    --device /dev/dri:/dev/dri \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    raylib_container
2

Use Software Rendering

If the error persists, switch to software rendering:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e LIBGL_ALWAYS_SOFTWARE=1 \
    raylib_container
Error Message:
failed to load driver: iris
failed to load driver: radeon
failed to load driver: nouveau
# (or other GPU-specific drivers)
Cause:The container cannot load the specific graphics driver for your GPU (Intel Iris, AMD Radeon, NVIDIA, etc.). This is a hardware acceleration compatibility issue.Solution:
1

Verify DRI Device Mapping

Double-check that DRI devices are mapped:
docker run -it --rm \
    --device /dev/dri:/dev/dri \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    raylib_container
2

Switch to Software Rendering

Use software rendering to bypass driver issues:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e LIBGL_ALWAYS_SOFTWARE=1 \
    raylib_container
Software rendering uses the CPU instead of the GPU and works across all hardware configurations.

​
When to Use Each Rendering Mode

Hardware Acceleration

Use when:
  • You need maximum performance
  • Your GPU is compatible
  • No driver errors occur
Command:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    --device /dev/dri:/dev/dri \
    raylib_container

Software Rendering

Use when:
  • Hardware acceleration fails
  • You see MESA, DRM, GLX, or driver errors
  • Compatibility is more important than performance
Command:
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e LIBGL_ALWAYS_SOFTWARE=1 \
    raylib_container
Recommended Approach: Try hardware acceleration first (Option 1). If you encounter any graphics errors related to dri, glx, mesa, or drivers, switch to software rendering (Option 2).

​
xhost Command Issues

Error Message:
bash: xhost: command not found
Cause:The xhost utility is not installed on your system.Solution:Install the package that provides xhost for your distribution:
sudo apt-get install x11-xserver-utils
Error Message:
xhost: unable to open display ""
Cause:You’re trying to run xhost from a non-graphical session (e.g., SSH, TTY console, or before the display server has started).Solution:
1

Run from Graphical Session

Ensure you’re running the command from within a graphical session (desktop environment).
2

Verify DISPLAY Variable

Check that the DISPLAY environment variable is set:
echo $DISPLAY
If empty, you’re not in a graphical session.
3

Add to Startup Scripts

If you need this to run at login, add it to your graphical session startup scripts (.profile, .xinitrc, etc.), not to shell RC files.

Build docs developers (and LLMs) love

Get started for freeTalk to us