Some Linux packages are intended to be headless, and as such, don't have the headful AWT library nor dependencies on X11 or other graphics libraries. If a user runs a headful program from a terminal window on such an installation by mistake, they get a cryptic exception rather than a Headless exception.

For example, running the attached test program on a Linux installation without the headful AWT library, libawt_xawt.so, will cause the following UnsatisfiedLinkError to be thrown:

$ java SimpleSwingApp
Exception in thread "main" java.lang.UnsatisfiedLinkError: Can't load library: <java_home>/lib/libawt_xawt.so
at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2408)
at java.base/java.lang.Runtime.load0(Runtime.java:785)
at java.base/java.lang.System.load(System.java:1989)
at java.base/jdk.internal.loader.NativeLibraries.load(Native Method)
at java.base/jdk.internal.loader.NativeLibraries$NativeLibraryImpl.open(NativeLibraries.java:331)
at java.base/jdk.internal.loader.NativeLibraries.loadLibrary(NativeLibraries.java:197)
at java.base/jdk.internal.loader.NativeLibraries.loadLibrary(NativeLibraries.java:139)
at java.base/jdk.internal.loader.NativeLibraries.findFromPaths(NativeLibraries.java:259)
at java.base/jdk.internal.loader.NativeLibraries.loadLibrary(NativeLibraries.java:249)
at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2413)
at java.base/java.lang.Runtime.loadLibrary0(Runtime.java:848)
at java.base/java.lang.System.loadLibrary(System.java:2025)
at java.desktop/java.awt.Toolkit$2.run(Toolkit.java:1384)
at java.desktop/java.awt.Toolkit$2.run(Toolkit.java:1382)
at java.base/java.security.AccessController.doPrivileged(AccessController.java:318)
at java.desktop/java.awt.Toolkit.loadLibraries(Toolkit.java:1381)
at java.desktop/java.awt.Toolkit.initStatic(Toolkit.java:1419)
at java.desktop/java.awt.Toolkit.<clinit>(Toolkit.java:1393)
at java.desktop/java.awt.EventQueue.invokeLater(EventQueue.java:1316)
at java.desktop/javax.swing.SwingUtilities.invokeLater(SwingUtilities.java:1421)
at SimpleSwingApp.main(SimpleSwingApp.java:40)

It works as expected if the user runs the program with '-Djava.awt.headless=true'.

I note that there is already precedent for automatically setting headless mode. If the DISPLAY env variable is not set, a warning will be printed and headless mode will be set. Similarly, perhaps a message about this being a headless installation could be printed if the libawt_xawt.so library is not present.