What causes the error "Can't connect to X11 window server"?

Nathan Meyers

The Sun AWT classes on Unix and Linux have a dependence on the X Window System: when you use the classes, they expect to load X client libraries and be able to talk to an X display server. This makes sense if your client has a GUI... unfortunately, it's required even if your client uses AWT but does not have a GUI. For example, you need access to an X server to use the java.awt.BufferedImage class.

Access to an X display server means a few things:

  • An X display server is running somewhere.
  • The environment in which you run Java includes an environment variable DISPLAY identifying how to reach the server.
  • There are no security settings in the server to prevent your client from opening a connection.

In general, if you're running your program from a terminal within the X Window System, all these things are true and the program just works. If you can run other X applications, like xterm or xclock, you should be able to run your Java AWT application.

In non-graphical environments, such as a servlet engine, your program may not know how to find or connect to an X display server. A common solution here is to run a special non-display version of the X display server, Xvfb, and set DISPLAY to point to it.

New information for JDK1.4: JDK1.4 evidently includes a new property that will allow the AWT to run in a headless (without a display) environment. This setting is supposed to solve the problem: java.awt.headless=true