Non-ASCII Characters display as square characters in Confluence
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Problem
Non-ASCII (Latin) characters are not being displayed or are replaced with squares. This is known to appear in at least the below areas:
- Title of Confluence Macros
- Thumbnail of attachment
- Preview of attachment
- Attachment title in an exported pdf
Diagnosis
Diagnosis steps
- Open Confluence editor
- Insert Status Macro and set "いろは" in macro title → If the title is garbled as squared character, Cause 1 or 4 may be affected
- Insert Office file which has a characters "いろは" inside. → If the thumbnail and preview is garbled, Cause 1,2 or 4 may be affected
- If you experience above in Confluence Data Center 6.10.x and later and sandbox feature is enabled, Cause 1,2,3 or 4 may be affected
Cause
Cause 1
The garbled characters are being shown as an image and it's generated on the server-side. It means that an appropriate OS font isn't installed on the server.
Cause 2
JVM cannot render thumbnail or preview of Office files like Powerpoint due to a lack of JVM parameters. CONFSERVER-36557 - Getting issue details... STATUS
Cause 3
The above JVM parameters in Cause 2 are not specified for JVM that runs Document Conversion Sandbox introduced in Confluence Data Center 6.10.x. CONFSERVER-57588 - Getting issue details... STATUS
Cause 4
Please refer to CONFSERVER-53263 - Getting issue details... STATUS and CONFSERVER-53262 - Getting issue details... STATUS for latest information.
An ASCII font Arial is used to render non-ASCII characters because it is configured as a default font.
Resolution
The content on this page relates to platforms which are supported by Confluence, however these are out of scope of our Atlassian Support Offerings. Consequently, Atlassian can not guarantee providing any support for it. Please be aware that this material is provided for your information only and using it is done so at your own risk.
Windows
If Confluence is running on Windows OS, you cannot solve this problem because it's not possible to install font in JVM. To resolve this problem, a feature request to allow user to install font from Confluence is raised as below.
CONFSERVER-34415 - Getting issue details... STATUS
Linux
If Confluence is running on Linux OS, you can solve this problem by installing missing fonts.
Examples below are provided for CentOS/Redhat and Ubuntu systems. For other Linux flavours, please refer to your system's manual or reach out to your Linux administrator.
For cause 1
Shutdown Confluence
Install
fontconfigCentOSyum install fontconfigUbuntuapt-get install fontconfig- Copy TTF files for expected font to font directory (typically in
/usr/share/fonts), otherwise install font assudo apt-get install fonts-arphic-ukai fonts-arphic-umingYou can check if the font is installed properly with
fc-list# fc-list IPAGothic,IPAゴシック:style=Regular IPAPGothic,IPA Pゴシック:style=Regular IPAMincho,IPA明朝:style=Regular IPAPMincho,IPA P明朝:style=Regular Create
fallbackdirectory under$JAVA_HOME/jre/lib/fonts. (If you installed Confluence in the default destination and used Java that is bundled in Confluence installer, then you will executemkdir -p /opt/atlassian/confluence/jre/lib/fonts/fallback)sudo apt-get install fonts-baekmuk ttf-baekmuk fonts-nanumCopy the desired TTF files in step 3 into the
fallbackdirectory created in step 4.Restart Confluence
- Clear the browser cache
Test by viewing the page containing the affected macro
For cause 2
In addition to the resolution for cause 1, add following JVM parameters in /opt/atlassian/confluence/bin/setenv.sh
CATALINA_OPTS="-Dconfluence.document.conversion.fontpath=<font-path> ${CATALINA_OPTS}"
CATALINA_OPTS="-Dconfluence.document.conversion.slides.defaultfontname.regular=IPAGothic ${CATALINA_OPTS}"
CATALINA_OPTS="-Dconfluence.document.conversion.slides.defaultfontname.asian=IPAGothic ${CATALINA_OPTS}"
CATALINA_OPTS="-Dconfluence.document.conversion.slides.defaultfontname.symbol=IPAGothic ${CATALINA_OPTS}"
CATALINA_OPTS="-Dconfluence.document.conversion.words.defaultfontname=IPAGothic ${CATALINA_OPTS}"
For example, /usr/share/fonts/ is set for <font-path> placeholder above.
For cause 3
If you are running Confluence Data Center and sandbox feature is enabled, you need to add following JVM parameters in /opt/atlassian/confluence/bin/sentenv.sh
CATALINA_OPTS="-Dconversion.sandbox.java.options=-Dconfluence.document.conversion.fontpath=<font-path>,-Dconversion.sandbox.java.options=-Dconfluence.document.conversion.slides.defaultfontname.regular=IPAGothic,-Dconfluence.document.conversion.slides.defaultfontname.asian=IPAGothic,-Dconfluence.document.conversion.slides.defaultfontname.symbol=IPAGothic,-Dconfluence.document.conversion.words.defaultfontname=IPAGothic ${CATALINA_OPTS}" For example, /usr/share/fonts/ is set for <font-path> placeholder above.
For cause 4
- Please note this is just a workaround that may not cover all cases. Check CONFSERVER-53263 - Getting issue details... STATUS and CONFSERVER-53262 - Getting issue details... STATUS for fundamental measures.
Removing font may affect some function of the operating system. Reinstall again if you encounter any unexpected behavior.
Remove Arial font from your OS that runs Confluence.
To remove cache which has already been rendered
After the steps above,
- Stop Confluence
- Delete the files in
<confluence_home>/viewfile/<confluence_home>/thumbnails/<confluence_home>/shared-home/dcl-document/<confluence_home>/shared-home/dcl-document_hd/<confluence_home>/shared-home/dcl-thumbnail/
- Start Confluence
For more information regarding this configuration option, including how to identify the fonts to install, please refer to Font Configuration Files documentation from Oracle.