Spring Boot Linux DocumentException: /fonts/simsun.ttf is not a valid TTF file

When working with Spring Boot applications on Linux, you may encounter a "DocumentException: /fonts/simsun.ttf is not a valid TTF file" error. This error usually occurs when you are trying to generate or manipulate PDF documents using libraries like iText or Apache PDFBox.

Understanding the Error

The error message suggests that the font file simsun.ttf is not a valid TrueType Font (TTF) file. TrueType is a widely used font format that provides high-quality display and printing for digital typography.

In order to understand why this error occurs, it's important to understand how fonts are used in PDF generation. When you generate a PDF document, you can specify the font to be used for text elements. If the specified font is not available or not valid, the PDF generation process will fail.

Font Configuration in Linux

Linux systems typically use fontconfig for managing fonts. Fontconfig provides a unified interface for locating and configuring fonts on the system. It uses a set of configuration files to define font properties and their corresponding files.

The error message suggests that the font file simsun.ttf is not being recognized as a valid font file by fontconfig. This could happen due to various reasons, such as incorrect font configuration or the font file itself being corrupted.

Troubleshooting Steps

To resolve the "DocumentException: /fonts/simsun.ttf is not a valid TTF file" error, you can try the following troubleshooting steps:

1. Verify Font File

First, make sure that the simsun.ttf font file is present in the correct location (/fonts) and is not corrupted. You can use the file command to check if the file is recognized as a TrueType Font:

$ file /fonts/simsun.ttf
/fonts/simsun.ttf: TrueType font data

If the file is not recognized as a TrueType Font, you may need to obtain a valid font file or try using a different font.

2. Check Font Configuration

Next, check the font configuration on your Linux system. The font configuration files are typically located in the /etc/fonts directory. The main configuration file is fonts.conf, and it includes other configuration files from the conf.d directory.

Inspect the font configuration files and make sure that the font directory (/fonts) is included in the list of directories that fontconfig searches for fonts.

<!-- /etc/fonts/fonts.conf -->
...
<dir>/fonts</dir>
...

If the font directory is not included, you can add it to the configuration file and restart the fontconfig service:

$ sudo nano /etc/fonts/fonts.conf

<!-- Add the following line to include the /fonts directory -->
<dir>/fonts</dir>

$ sudo systemctl restart fontconfig

3. Rebuild Font Cache

Fontconfig maintains a font cache file that speeds up the font searching process. If the font cache is outdated or corrupted, it can cause font recognition issues.

To rebuild the font cache, you can use the fc-cache command:

$ sudo fc-cache -f -v

This command regenerates the font cache by scanning the font directories and updating the cache file.

4. Verify Font Availability

Lastly, you can verify that the font is available and recognized by fontconfig using the fc-list command:

$ fc-list | grep simsun

This command lists all available fonts and filters the output for the keyword "simsun". If the font is listed, it means that fontconfig recognizes it as a valid font.

Conclusion

The "DocumentException: /fonts/simsun.ttf is not a valid TTF file" error occurs when the specified font file is not recognized as a valid TrueType Font by fontconfig on Linux. By following the troubleshooting steps outlined in this article, you can resolve the error and ensure that the font is correctly recognized and available for PDF generation.

Remember to always check the font file's validity, verify the font configuration, rebuild the font cache, and ensure that the font is available and recognized by fontconfig.