My Mermaid renderer drew tofu boxes instead of labels — the container had no fonts installed

Mermaid is a tool used to create diagrams like sequence diagrams and flowcharts for APIs and release flows. However, there is rarely an output device capable of displaying these diagrams. To address this issue, the author built a renderer called the Mermaid Diagram Renderer API. This API allows users to post Mermaid syntax and receive a base64 PNG or SVG in return. Yet, the first version of the renderer looked fine in tests but broke when exposed to real input.

Upon investigating, the author discovered that the issue stemmed from the Dockerfile used to build the renderer. A slim base image was employed, and headless Chromium was installed for rendering, but no font packages were included. Without fonts, the renderer was unable to rasterize text, resulting in tofu glyphs appearing instead of labels.

This occurred because Mermaid sizes nodes by measuring text width before drawing it. With no usable font, those measurements collapsed, causing node boxes to shrink to near-nothing and arrows to overlap.

The root cause of the problem was that Mermaid performed measurements using a font for typography, different from the one used for rasterization. To resolve this issue, the author installed the fonts-liberation package along with Noto and added a fc-cache -f layer step. Additionally, a pinned font-family was specified in the render options to ensure that both measurement and rasterization utilized the same font.

To prevent similar issues in the future, the author also added a canary test, a small flowchart with a known label, and compared its pixel histogram on every deployment, halting the process if the label pixels were absent. This example highlights the importance of including fonts as a first-class dependency in headless-browser rendering within containers and emphasizes the need for tests that verify the presence of content pixels within an image, not just its existence.