Some test text!

Hamburger Icon

Cli / Guides / Troubleshoot

Common solutions when troubleshooting DocPub

Why do conversions stop working after entering API key and secret (Error Code 4)?

DocPub returns with error code 4 if connection with Apryse servers wasn't established. To help identifying what's the issue you can run DocPub with a "--verb 2" option, which would print additional information to the command line. These are the error messages you will see if something goes wrong:

1) Can't establish a connection due networking error; Check your connectivity to the internet and firewall settings.

2) Credentials provided for authentication are incorrect. Make sure you are subscribed to pay as you go plan. You can check your subscription plan and credentials at

3) Server is not responding. If the error persists contact

4) Server is not recognizing a conversion. Please contact

Why is a white space separating neighboring pictures?

In some cases, XPS viewers that support anti-aliased rendering produce line/space artifacts at neighboring picture elements (e.g. for image tiles or polygons sharing common edges). These artifacts are not a byproduct of DocPub conversion, but are produced due to anti-aliased rendering in the XPS viewer. The same issue applies to the input PDF document however the current PDF viewers are typically better at handling this type of issues. The aliasing artifacts should not be visible during printing or high-resolution output.

Why are some pages rasterized?

Occasionally, there will be documents that don't allow for an accurate conversion. In these cases DocPub will by default render the necessary elements at dpi or for XOD documents at the resolution given by the '---dpi' parameter. In other select cases, to generate the exact appearance of the original document, an entire page may need to be rendered. In these cases rendering can be disabled using the '--norender' option. Disabling rendering will preserve resolution independent properties of input PDF documents (including fonts, paths, and shadings) as well as text selection and extraction capability in XPS processing software. Note that when flattening option is enabled that content may still get rasterized, but for different reasons.

Why are some fonts in PDF not rendered consistently?

PDF format, unlike XOD, does not require mandatory font embedding. As a result PDF consumers, such as DocPub and your favorite PDF viewer, need to find substitute fonts for missing fonts on the client system. Unfortunately, this means that there is no guarantee that file will render accurately on different systems or even in different PDF viewers. Default font substitution can be overridden using PDF SDK which offers additional options that are not available in the DocPub Command-Line Utility. To avoid font substitution errors, simply make sure to create PDF documents with all fonts embedded. If you cannot guarantee embedded fonts, then make sure the converting computer has the required, or similar, fonts installed. DocPub will do its best to match missing fonts with existing ones on the system.

Why is the image quality so low?

To prevent file size from getting too large there is a maximum size for images. This also allows the generated document to be viewed on low resource devices where there are megapixel limits. You can tell that this limit has been reached when increasing the DPI has no effect. You can therefore increase the --max_image_pixels to a value of say 3 or 5 million, which should suffice. If you don't want any limit then put in a very large number.

Why does the Silverlight plugin crash?

Unfortunately there is a long standing bug in Silverlight that causes it to crash when there are rotated text/glyphs. If you are encountering this issue, then use the -- silverlight_text_workaround flag. This has the downside of the text no longer being selectable.

Why do shadows (masks) not appear correctly in Silverlight?

Silverlight does not provide full support for opacity masks as specified in the XPS format. If the generated output does not appear correct in Silverlight then set the --mask_workaround flag, which will detect and then rasterize these cases so they appear correctly, but no longer support zooming.

How do I stream XOD conversions?

To stream the generated XOD file as it is converted simply set the --console_out flag. With this flag the output is sent to the standard out pipe, so you can redirect the pipe to anything you like.

Get the answers you need: Chat with us