I've written a Java app with a GUI to run on the Rasp Pi. It runs OK with keyboard, mouse and display attached to the Pi.

This has been fine for development, but I want to run the Pi without it being attached to anything, and to interact with the Java GUI via remote control. I have the remote control working OK, but when I try running the Pi without attachments, I get a Headless exception. I've never come across this exception before.

Do I need to install headless Java? If I do, will it still display the GUI OK?


  • Does it count as headless if there is a GUI that is present on the remote system? Note that a SSH session isn't in itself a GUI but a CLI (or Text User Interface - TUI) but you can run an remote Xserver and display a GUI on that. On the other hand if the application is running on a headless Pi even when you are not connected to it then I guess that is the case where you need that Java version. I do not think it is mutually exclusive with the "normal" version - I guess you just need to invoke the right one for your application.
    – SlySven
    Jan 12, 2016 at 4:39

2 Answers 2


Java should only throw that exception if you deal with gui components (like Swing). check all your imports for javax.swing and make sure you don't reference any.

also, don't use javaw to run it, use Java. Not sure this will make a difference, but javaw is really for GUIs only and you don't get access to stdout.

If a library you are using instantiates a swing component, you may be out of luck. You can test by starting with a tiny "Hello, world" app which should work, then re-add pieces.

If you even reference a class that imports swing this MAY cause a problem (I'm not sure), but again, start with a "Hello, world" basic app and add pieces back in until it breaks.

If you look carefully at the exception, it should tell you exactly where the problem was.

If you want to run either headless or not--try to separate all the GUI stuff into one class. You may be able to attempt to instantiate that class and catch the headless exception--if you get that exception then go CLI, otherwise everything works.

  • Oh dear. I've written my whole app using Swing and it works fine with a display attached to the Pi. I'd assumed I'd be able to interact without a display, just using remote control. My app controls a lot of valves, and changing one valve can change the values of other valves. Buttons and a display of the state of each valve seemed a logical solution. It looks like I'll have to think again. Thanks.
    – pir8ped
    Jan 11, 2016 at 19:25
  • There are various patterns that separate view from the rest of your code--and this is why :) (google MVC or MVP) The easiest solution is probably to pull the business logic out and make a console version separate from your GUI version. While you do so, if you put most of your business logic in a separate class, both of your "apps" should be able to use the same core code. Also if you remote in with RDP, even without running "startx" your gui should work (rdp starts a little gui on it's own I think, so it's not a great solution).
    – Bill K
    Jan 11, 2016 at 19:40
  • I may have misunderstood--if you don't think you can use a CLI (if the GUI controls are necessary) then you cannot run headless--a GUI requires an OS windowing system. If this is the case there are 2 solutions, RDP or a client/server where you write a headless server for the PI and a GUI for your PC and have your PC send messages to the server. This server can use any number of communication protocols from raw sockets to a restless web server. If you don't know anything about this stuff, try an RMI tutorial to get started.
    – Bill K
    Jan 11, 2016 at 19:48
  • Sorry for all the comments, but you got me thinking and I figured there MUST be a server out there somewhere. I googled and found this: github.com/projectweekend/Pi-GPIO-Server. I'm not sure what all that supports--I've barely looked at it--but if you ran that server on your PI then you should be able to code a client that would run either on the PI or a PC and use that server to do it's dirty work. There were other hits if that doesn't work out for you. Using a web interface will probably be more familiar than RDP if you don't use java much.
    – Bill K
    Jan 11, 2016 at 19:53
  • I'm very familiar with MVC and have done a lot of web server stuff using Java. Using Swing was simpler for what I'm aiming for. I'd just never heard of the headless issue before, and I assumed I could control my app via remote control without any issues. I'd rather try to find a way round not requiring a display than to rewrite the whole thing as a client/server, but it might come to that.
    – pir8ped
    Jan 11, 2016 at 20:04

If Swing uses plain X11 as backend , it should be impossible for Java to detect a missing display since the X Server runs fine without a physical display.

This will "just work" as long you always let the desktop running.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.