In this page

Configuring app logging

When investigating a run-time problem, you may need to increase the logging level for the app. Doing so, the app writes more run-time details to the Jira log which helps us understand what's going on.

To increase the logging level from the web interface without stopping Jira:

  1. Login to Jira as administrator.
  2. Go to Jira AdministrationSystemLogging and Profiling.
  3. Click Configure logging level for another package under Default Loggers.
  4. Enter "com.midori" to Package Name and choose "DEBUG" in Logging Level. (You can alternatively choose "TRACE", the most detailed logging level, but it may produce a very high number of log entries.)
  5. Click Add.
  6. Check if this new package was correctly added to the Default Loggers list.

Now execute the app function that you think fails, and check your Jira log to see the details.

If you can't understand the log lines, report what you have found to our support. We are there to help you.

Typical problems and their solutions

I cannot export more than 1000 issues in one turn.

To prevent overloading the server, Jira exposes a limit on the number of issues that can be exported in one go. The Better PDF Exporter fully obeys this limit.

The limit is set to 1000 by default, but can be overridden by configuring the following settings in

  • This is the default soft limit. Soft means that this value will be automatically added as a URL parameter called tempMax to each export request. You can manually increase the default value by changing the URL in your browser's address bar, or even remove the tempMax request parameter from the URL. You cannot exceed the value defined by the next configuration setting this way.
  • This is the absolute hard limit. You cannot set tempMax to values greater than this, as you will get a 403 HTTP error. However, you can grant some users the permission to even break this limit - see next setting!
  • If you select a group here, any of its members can export an unlimited number of issues. Note that you still need to override the tempMax URL parameter by hand. Also be careful, as these users will be potentially generate huge load on the server.

For more detailed explanation of these settings, please see the official Atlassian documentation.

Please note that in modern Jira versions these settings are configurable also through the UI!

Font related problems

I see '#' characters instead of Cyrillic / Chinese / Japanese / etc. characters in the PDF files.

The most typical problem with fonts is that your document contains a character, but its glyph (symbol) is not available in the supplied font. For example, your issue description contains a Chinese character, but the supplied font does not contain any Asian glyph.

When the glyph for a character is not found, the renderer will replace it with the hash character '#' in the final PDF document. It means that seeing unexpected hash characters in the document is the typical indicator of the problem. Please note that even with this, the PDF document will be successfully rendered and will be a valid file.

Depending on the number and importance of the missing glyphs:

  1. The document may be usable if only a single unimportant glyph was missing (like an emoji).
  2. The document may be unusable if a high number of important glyphs were missing (like all Kanji and Kana in a Japanese document).

If it is the latter, use automatic (easier) or custom fonts (more control).

I see "Times" or "Times New Roman" being used in my PDF instead of the custom font I set in the template.

When you are trying to use a font family in the FO template, but the corresponding font file is not found by the renderer, it will use "Times" instead. Unexpectedly seeing "Times" indicates that the custom font is not properly configured.

Review your custom font configuration and check the following typical problems:

  1. Whether the font directory is existing in the filesystem.
  2. Whether the font directory name is correctly set to the <directory> element in fop-config.xml.
  3. Whether the font file is existing in that directory.
  4. Whether the font family name is correctly set to the font-family="myfont" attribute.
I see " .fop (Permission denied)" exceptions.

The PDF renderer may try to use a cache file to speed up its font-related operations. This exception is thrown if the cache file cannot be created in the filesystem due to permission problems, i.e. if the operating system user who started the Jira process cannot write to the filesystem in a certain location.

As caching does not affect the performance of the export, unless you make heavy use of a large number of fonts, we suggest disabling caching. For that, add this setting to the fop-config.xml file (which you can edit similarly to a PDF templates):

<!-- ... -->

<!-- default page dimensions in case value is specified as "auto" -->
<default-page-settings height="11in" width="8.26in"/>

<!-- disable caching (to avoid the potential ".fop (Permission denied)" problem) -->
<use-cache>false</use-cache><!-- this is the line to add! -->

<!-- DO NOT DELETE: substitutions for the "auto" pseudo font family -->

<!-- ... -->

Note that caching is disabled by default since app version 7.3.0. Therefore, the problem will not occur in those versions.

I see "Only 0 of the 4 expected font substitutions updated to font family Arial Unicode MS" warnings.

This occurs when you are using automatic fonts, but the configuration file fop-config.xml is broken. You have possibly removed some sections, which are required by automatic fonts, from that.

Solution: save a backup of your current fop-config.xml, restore the file to its factory default state, then re-apply your customization if there were.

I see "java.lang.UnsupportedOperationException: ... not yet supported" exceptions when using a custom font.

Certain fonts may use special features known as "complex scripts" which are not yet supported by the PDF renderer. For example, the Roboto font is known to cause this issue.

If you are working with European languages only, you can safely disable the "complex scripts" feature:

  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsPDF Templates.
  3. Open the fop-config.xml file.
  4. Apply the change explained at point 3 in the Disabling complex scripts section.
  5. Save your changes.

Gadget-related problems

I get errors when exporting a dashboard that contains Sprint Burndown or Wallboard gadgets.

For the investigation of these kind of problems, we need to know more details about the board, the sprint, the issues and the changes during the sprint. Follow these steps:

  1. Open the problematic dashboard in your browser.
  2. Take a screenshot about the problematic gadget.
  3. Hit F12 to open the Developer Tools view (built to your browser).
  4. Click the Network tab and clear the logs if any is visible.
  5. Refresh the dashboard in the browser, and wait till it is completely finished loading.
  6. Search for scopechangeburndownchart.json (in case of Sprint Burndown Gadget problem) or allData.json (in case of Wallboard Gadget problem) in the list of URLs.
  7. Click it to show the request's details in the right, then click the Response tab.
  8. Copy the whole JSON string shown, and paste that into a new text file.
  9. Attach both the image file and the JSON file to the support ticket. This helps us to see the expected output (image) and the input (JSON).

The instructions above are made for Google Chrome, but very similar steps should be taken in other types of browsers. It should be trivial, but feel free ask our help any time.

Other problems

Table borders and underlines are blurred and are drawn with varying line thickness.

When viewing a PDF file in Adobe Reader, especially those with tables and lines, some lines may look thicker than other lines and even different sections of the same line may look somewhat blurry. It is caused by the "Enhance thin lines" feature of Adobe Reader, designed for lower resolution CRT monitors.

To enhance the look, turn off the feature in your Adobe Reader: navigate to EditPreferencesPage Display and uncheck the Enhance thin lines option. There is an additional option called Smooth line art that can make your lines laser-sharp, but can also cause other visual artifacts at line junctions (e.g. borders at the table corners). Find the combination that works best for you.

Unfortunately, these display settings are local (specific to your computer), not attributes of the PDF file itself.


Ask us any time.