Headless Java rendering

Hi all, today I am going to write about an issue I met when I was trying to generate a excel sheet in a spring boot app which runs inside a docker container.

When I try to generate the xsel sheet from the spring boot app which runs inside of a docker container it gave me this error ,

java.lang.RuntimeException: Fontconfig head is null, check your fonts or fonts configuration

When I executed the spring boot app locally without building the docker image and the container it generated the excel sheet, but when I try it with docker container it didn’t and gave me the above error.

For this my conclusion was it might happen because we have not installed the needed fonts inside the docker container. In the research of this I found this error called “Headless Java rendering” . Let’s see what is this,

Get Duleep Alwis’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Java normally relies on the Abstract Window Toolkit (AWT) or Swing for rendering graphics, fonts, images and GUIs. But in environments like servers or containers like Docker where there is no display or GUI , Java runs in headless mode, which means,

• There is no screen
• No mouse/keyboard interaction
• No system font or UI components loaded by default.

This happens when you try to generate ,

• Images (ex.:- captchas, charts)
• PDFs (with embedded fonts)
• Excel with grpahical content
• Anything using Graphics2D in memory.

Since we were trying to create sheets in the workbook created using apache poi library in the code we called a method called autoSizeColumn() which uses Java AWT’s FontMetrics and Graphics2D internally to measure the width of the text, so it requires graphical (non-headless) environment with fonts installed.

Therefore when running headless mode (Docker , Linux server) when fonts are missing you get the above error.

Therefor my solution was to install required fonts inside the docker container . This is how it can be done in the DockerFile of the spring boot project.

We were using amazoncorretto:21.0.4-alpine this base image for creating the docker image, therefore our package manager for this will be apk.

# Use Alpine-based Amazon Corretto (Java 21)
FROM amazoncorretto:21.0.4-alpine

# Install system fonts for AWT, POI, iText, etc.
RUN apk add --no-cache \
    fontconfig \
    ttf-dejavu \
    && fc-cache -fv

# Set headless mode to avoid AWT GUI errors in POI/iText
ENV JAVA_TOOL_OPTIONS="-Djava.awt.headless=true"

# Create directory for the app
WORKDIR /app

# Copy the Spring Boot JAR
COPY target/your-app.jar app.jar

# Run the app
ENTRYPOINT ["java", "-jar", "app.jar"]

With this kind of solution we were able to fix the issue and generate the excel sheet successfully.

You better try this in your local machine and get the experience of this. I will meet you with another article like this next time. Until then enjoy your life………