Deploy a MapObjects Java or ArcIMS Java component on a UNIX machine without a graphics environment (headless)

Last Published: April 25, 2020


Some MapObjects Java and ArcIMS Java libraries require the availability of the java.awt package. Most versions of the java.awt library on UNIX require a graphics environment supported by a functioning X server. The X server and the DISPLAY environment variable need to be set correctly. However sometimes Java applications and libraries dependent on the java.awt package must be deployed on a machine without a local graphics environment.
A common error when a valid graphics environment cannot be found is:

"Can't connect to x11 window server using ':0.0'"

Below is a list of possible solutions:


  • The best solution is to create a MapObjects Java application that is capable of running in headless mode. MapObjects Java 2.x includes server components that do not require a display environment to function. For example, the com.esri.mo2.ui.bean.Map AWT based component requires a display environment. Either replace instances of this object with a server-based Map component ( or integrate code within your application to accomodate a headless environment. Any component that requires a display environment will throw a HeadlessException when the current display environment is not supported (for example, one is not available). Use try/catch blocks to trap for this exception and use server-based components instead of visual, AWT based components. The following Java Virtual Machine command line parameter can be used to specify that no display environment is available for a Java application:


    This parameter can be used for testing and execution. This topic is discussed in greater detail at the following url:
    Headless Capabilities

    MOJava 1.x (included with ArcIMS 4.x and 9.x) does not have this capability - see other options listed below.

  • Use Xvfb (or X Virtual Frame Buffer).

    Xvfb is an X server emulator that can run on machines with no display hardware and no physical input devices. It can be found as part of x11 Release 6.4, a version of which is available from XFree86 at
    Another website that may provide useful information on this option is located at:
    When this process is running, the DISPLAY variable must be set to route back to local machine.

  • Use a remote X server.

    The java.awt package requires that your DISPLAY variable be set to a functioning X server.
    For example:

    setenv DISPLAY=remotehost:0.0
    export DISPLAY

    The ability of remote clients to connect to an X server by typing "xhost +" on the remote X server may need to be enabled.

Article ID:000006255

  • Legacy Products

Get help from ArcGIS experts

Contact technical support

Download the Esri Support App

Go to download options

Discover more on this topic