Non-ASCII Characters display as square characters in Confluence

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Server and Data Center Only - This article only applies to Atlassian products on the server and data center platforms.

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

  1. Open Confluence editor
  2. Insert Status Macro and set "いろは" in macro title  → If the title is garbled as squared character, Cause 1 or 4 may be affected
  3. Insert Office file which has a characters "いろは" inside. → If the thumbnail and preview is garbled, Cause 1,2 or 4 may be affected
  4. 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.

For cause 1

  1. Shutdown Confluence

  2. Install fontconfig

    CentOS
    yum install fontconfig 
    Ubuntu
    apt-get install fontconfig
  3. Copy TTF files for expected font to font directory (typically in /usr/share/fonts ), otherwise install font as sudo apt-get install fonts-arphic-ukai fonts-arphic-uming

    You 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
  4. Create fallback directory 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 execute mkdir -p /opt/atlassian/confluence/jre/lib/fonts/fallback )

    sudo apt-get install fonts-baekmuk ttf-baekmuk fonts-nanum
  5. Copy the desired TTF files in step 3 into the fallback directory created in step 4.

  6. Restart Confluence

  7. Clear the browser cache
  8. 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/sentenv.sh

Example to IPA Gothic as a default font
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}"

(info)  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}"

(info)  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,

  1. Stop Confluence
  2. 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/
  3. Start Confluence


(info) For more information regarding this configuration option, including how to identify the fonts to install, please refer to Font Configuration Files documentation from Oracle.

Last modified on Jan 28, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.