When a “Successful” Install… isn’t: A Domino on Linux Gotcha

Posted on by

While preparing for my Linux Installfest session for Engage, I figured I’d better walk through the Domino installation steps myself, just to make sure everything worked as expected.

That might sound routine, but here’s the catch: I almost never install Domino manually anymore. I usually rely on a script Daniel built, which saves a ton of time and effort. But for this session, the goal was to help participants understand what’s actually happening behind the scenes. So, back to basics it was, command line and all.

That’s when things got interesting.

The Mysterious “Instant Install”

Everything seemed to go smoothly at first. I answered all the usual installer questions, paths, users, licenses, you know the drill. Then came the moment where the actual installation should begin.

Except… it didn’t.

The installer just finished. Instantly. No errors, no warnings, nothing to suggest something went wrong. Just… done.

Of course, Domino wasn’t actually installed.

Digging into the logs, I found this less-than-friendly message:

java.lang.NoClassDefFoundError: java.awt.Toolkit (initialization failure)
...
Caused by: java.lang.UnsatisfiedLinkError: Failed to load library 
libXrender.so.1: cannot open shared object file: No such file or directory

That last line looked promising: it pointed to a missing library. But here’s the confusing part: when using the automated script, those packages aren’t installed either. So why was this suddenly a problem?

A Small Clue from My Terminal

The breakthrough actually came from something easy to overlook. In MobaXterm, my go-to terminal, I noticed this line in the session info:

X11-forwarding : ✓ (remote display is forwarded through SSH)

That checkmark was subtle, but important. It meant my session was set up to forward graphical output, even though the server itself didn’t have a GUI installed. In hindsight, that was a pretty strong hint about what was going wrong.

The Real Culprit: A Half-Detected GUI

After a bit of head-scratching, the root cause became clear.

The installer was detecting (or thinking it detected) parts of an X environment. Based on that, it tried to launch a graphical interface, even though the server didn’t actually have a GUI installed (and if you’re running a Domino server on Linux, you really shouldn’t have a GUI installed anyway).

Since the graphical components weren’t fully available, the installer failed silently and exited. No clear error, just a misleading “success.”

The Fix: Go Headless

The solution turned out to be simple, and no, it doesn’t involve installing a bunch of X11 packages.

Instead, you just need to tell Java explicitly to run in headless mode, meaning: no graphical interface, no assumptions.

Before starting the Domino installer, run this in your shell:

export JAVA_TOOL_OPTIONS="-Djava.awt.headless=true"

That one line prevents the installer from attempting to use any GUI components, and just like that, the installation proceeds exactly as it should.

Takeaway

Sometimes, the trickiest issues aren’t caused by what’s missing, but by what the system thinks is there.

If you’re installing Domino on a minimal Linux setup and run into a mysteriously “successful” install, this is definitely something to check.

And if you’re like me and usually rely on automation, well, it never hurts to revisit the manual process once in a while. You might learn something new… or at least rediscover an old quirk 😊