Free Support Forum -

Font Substitution Issue in Words for Java version 19.2+

The following code snippets (adjusted to account for the API change in the second snippet) demonstrate a change of behavior between versions 19.1 and 19.2+ of Aspose Words for Java when converting DOCX to PDF. The behavior is the same in OS X and in Debian. In each case the same document is used and the only difference in our application is the version bump of Aspose Words for Java (and the necessary changes to use the new API).

// Version 19.1 (Works as expected; "Amplitude" substituted for "AmplitudeTF")
com.aspose.words.FontSettings settings = new com.aspose.words.FontSettings();
settings.setFontSubstitutes("Amplitude", "AmplitudeTF");

// Version 19.2+ (Fails; substitution rule is ignored and "Times New Roman" is used instead)
com.aspose.words.FontSettings settings = new com.aspose.words.FontSettings();
FontSubstitutionSettings subSettings = settings.getSubstitutionSettings();
subSettings.getTableSubstitution().setSubstitutes("Amplitude", "AmplitudeTF");

// Response of 19.1
Font substitutes: 'Amplitude' replaced with 'AmplitudeTF'.

// Response of 19.2+
Font 'Amplitude' has not been found. Using 'Times New Roman' font instead. Reason: alternative name from document.

As best I can tell this is the correct “port” of the older API (19.1 and earlier) to the new one (19.2+). If we are using your API correctly the regression in font behavior is annoying and erodes confidence in your product.


To ensure a timely and accurate response, please ZIP and attach the following resources here for testing:

  • Your simplified input Word document you are getting this problem with
  • Aspose.Words for Java 19.10 generated output document showing the undesired behavior
  • Aspose.Words for Java 19.1 generated output document showing the correct behavior
  • The Font file
  • Please also create a standalone simple Java application (source code without compilation errors) that helps us to reproduce your current problem on our end and attach it here for testing. Please do not include Aspose.Words JAR files in it to reduce the file size.

As soon as you get these pieces of information ready, we will start investigation into your issue and provide you more information. Thanks for your cooperation.

Would you please first confirm that the code I originally posted is the correct transformation (port) when moving from 19.1 to 19.2+ to account for the API changes made in 19.2?


When using the latest version of Aspose.Words for Java i.e. 19.10, the following code should produce the expected results:

com.aspose.words.FontSettings settings  = new com.aspose.words.FontSettings();
FontSubstitutionSettings subSettings = settings.getSubstitutionSettings();
             new String[] { "AmplitudeTF" });

Thank you. I’ve confirmed that either “addSubstitutes” or “setSubstitutes” yields the same (incorrect) behavior for this document and font. I have to determine whether or not I can share this particular font with your company before I can put together any additional materials.

In the interim it seems that to the extent you are able, it would be worth investigating on your end what changed in the API move from 19.1 to 19.2+ that altered table-based substitutions that might explain this kind of behavior. I don’t imagine that this is document or font specific and other customers may be experiencing similar issues.


Please refer to the ‘Changes in Font Substitution Process and Public API’ section in the release notes page of Aspose.Words for Java 19.2.

Secondly, we need the resources mentioned in my previous post to be able to reproduce the exact same behavior on our end. It is safe to attach files in the forum. If you attach your documents/fonts here, only you and Aspose staff members can download them. We only need these resources for testing purposes.

Thank you for the link to the release notes. I did not realize that there was an explanation of the changes introduced in version 19.2.

I think I have identified the problem. In the new font resolution order step three (“3. AltName from FontInfo (if any)”) appears to be the problem.

Our document has this entry in its “fontTable.xml”:

<w:font w:name="Amplitude"><w:altName w:val="Times New Roman"/><w:panose1 w:val="00000000000000000000"/><w:charset w:val="00"/><w:family w:val="roman"/><w:notTrueType/><w:pitch w:val="default"/></w:font>

So the “altName” specifies “Times New Roman” which I should think is fine in itself. The new algorithm introduced in 19.2 however prevents any of the substitution logic from overriding the “altName” specified in the DOCX file.

If this is by design then we need a way of turning off step three to allow the font substitution rules to operate as before.

Thank you.

A post was split to a new topic: Provide Option to Turn Off Checking AltName from FontInfo


We have logged your requirement in our issue tracking system. Your ticket number is WORDSNET-19524. We will further look into the details of this requirement and will keep you updated on the status of the linked issue. We apologize for any inconvenience.


Regarding WORDSNET-19524, for this particular scenario, there is an easy workaround i.e. you can just clear the AltName field for each FontInfo in Document.FontInfos before the rendering. Could you please check and let us know if this will be acceptable for you? Thanks for your cooperation.

We will consider this approach and get back to you. Thank you.


Sure, we will wait for your further input on this topic.

I’m not sure that overriding the “altName” (ECMA-376-1:2016 supplied in the DOCX file is what we will want to do. This seems to violate the intent of the specification:

When an application cannot locate a font using the primary name stored on the font attribute of the font element (§, it should use each alternate name in term to attempt to locate the font, and use the first font for which is locates a match.

In this case the font cannot be matched by primary name due to the font matching algorithm in Aspose Words rather than the actual absence of the font.

We use your font substitution API (prior to 19.2) to correctly map the primary name so that Words can find it. Now that the matching algorithm changed in 19.2+ our hands are tied. Currently the algorithm is not robust enough to find the correct font on its own.

Font matching is not trivial so I don’t fault the current algorithm too much but without a way of helping it out (the way the substitution API used to work) Words tries to match the “altName” even though the primary name is technically available.

We would still like to see a way to allow this mapping to occur for proper recognition of the primary name.


Thanks for the additional information. We have logged these details/concerns in our issue tracking system and will keep you posted on further updates.