Troubleshooting

A [pdfink] shortcode can be used anywhere within WordPress where shortcodes are supported. For most users, this will primarily be within the content of a WordPress post, page, or widget. The [pdfink] shortcode will output a link, which when clicked, will manipulate the corresponding PDF before delivery.

Basic Troubleshooting

When something goes wrong with WordPress — anything — here are the basic troubleshooting steps to perform before asking for help. These steps are called basic because anyone can do them. Basic troubleshooting is a handy tool to keep in your back pocket for whenever ANYTHING goes wrong with WordPress.

Here are the two parts of basic WP troubleshooting:

  1. Revert to a default WordPress theme temporarily. A default WordPress theme is twentytwentythree, twentytwentyfive, etc. Now check if the problem is still there. Problem still there? Then it’s not a conflict with your theme. Great sleuthing!
  2. Deactivate all plugins except for PDF Ink and (WooCommerce/Easy Digital Downloads/Download Monitor, if you are using one of those). Yes, really, deactivate all of the others temporarily. Now check if the problem is still there. If the problem is still there, then the problem lies with PDF Ink (or an e-commerce integration, if applicable, or your server or WP installation). If the problem is gone, you have established a plugin conflict. Turn on the plugins one-by-one, checking your site each time until the problem re-appears. When it reappears after you’ve activated a certain plugin, you’ve established which plugin is causing a conflict.

If you are writing for support, we will likely ask whether you have performed basic troubleshooting. We just want to know that it isn’t a plugin or theme conflict. Why? Because there are billions of combinations of plugins and themes out in the wild, and we cannot account for how they all interact. We’ll leave this part of debugging up to you.

Further Steps

Before going down this line, we recommend you turn on PDF Ink debugging (errors, warnings, and notices) and watch the logs as you operate the plugin! PDF Ink will probably tell you exactly what is happening… in the logs. Turning on WP debugging will catch items that PDF Ink debugging might have missed, providing the most debugging information possible. Both can be turned off when you are finished sleuthing.

  1. If you are integrating with Woo/EDD/DM, make sure “Global Stamping” is turned on in the Integration settings or make sure stamping is enabled at the product/download level. If you’ve turned on stamping, then make sure you are either setting content or encryption/passwording/permissions. Otherwise there is nothing to see (no changes are made to the PDF)!
  2. Make sure your uploaded PDF file is not already encrypted/passworded. Unless you are using SetaPDF-Stamper and have set the owner password in settings, PDF Ink needs full access to the PDF guts to do its magic! In other words, the free PDF readers included in PDF Ink cannot open passworded PDFs.
  3. If your stamp contains special characters, please try one of the included fonts other than Helvetica, Courier, or Times Roman. Some font files are subsetted to include more international characters, like those seen in French and Polish, for example. Learn more about this.
  4. Maybe see that your original file name doesn’t contain spaces. Replace blank spaces with dashes or underscores and remove any odd symbols. This isn’t usually the cause of problems, though.
  5. Try another library set.

Trouble “outlaw” PDFs

“PDF” is an open specification that describes a file design (e.g. how to build and read/display PDFs). Because it is an open specification, it means that literally anyone can build a PDF or a PDF reader application without any oversight or verification that it is semantically correct.

There are a LOT of iffy PDFs and PDF reader applications out there that work “good enough” for the average person, but which do not adhere to the specifications. This makes it very difficult to build a PDF parser that could ever account for all this diversity. This “WILD WEST of PDF” is a common hurdle for anyone working with “the guts” of PDF files, including us.

Steps to Try with Outlaw PDFS

Some PDF files are mildly corrupted and/or un-readable by the open-source parsers included in the plugin (FPDI/TCPDI).

First, please try stamping another PDF to rule out this problem.

Secondly, re-saving a broken PDF with Apple Preview (“Export as PDF”) or Adobe Acrobat can sometimes help clean it up so PDF Ink can do its job.

Finally, if you must must must parse this PDF of yours, upgrade to SetaPDF-Stamper. SetaPDF-Stamper includes provisions for repairing broken PDFs and will handle just about any PDF which is within minimum PDF specification. If you cannot upgrade to SetaPDF-Stamper and steps 1 and 2 just listed do not work for you, we are not sure what else to recommend other than not manipulating this file. It is up to you to repair/re-create your PDF or upgrade your library.

Error Messages

Ack! That’s horrible! Here are what the most common error messages mean:

Uncaught exception ‘InvalidArgumentException’ with message ‘Cannot open’…

If you get this error while trying to stamping a file, it means the PDF reader could not open the PDF. Make sure the PDF is where the computer thinks it is. Double check your file paths, and that the PDF is where you think you put it. Also make sure your filename does not use unsafe characters like spaces in the PDF file name. Replace spaces with dashes or underscores or remove them.

Warning: fopen(): remote host file access not supported

If you get this message it’s because you’re trying to store your PDF on another host (another domain). An attempt was made to fetch the file from that remote server, but failed, possibly due to the location not being a valid url or missing authentication. It might also be that a higher timeout needs to be set (you could use the `http_request_timeout` or `pdfink_remote_get_timeout` filter for this), but then again… ask yourself if you really want to be bringing files in from a remote server, processing them on your server, then sending them out again.

Fatal error: Allowed memory size of n bytes exhausted

If you get this error and are using TCPDF, please refer to “Performance tuning.” TL;DR: start by upgrading your PHP installation and increasing your PHP memory limits. Simplify your stamp by removing HTML, images, fonts, and/or encryption. FPDF/TCPDF makes a huge demand on the server after FPDI/TCPDI parses the entire PDF into memory, in order to spit the PDF back out with the watermark added. If you have a large PDF and a complex watermark to add to it, and are expecting affordable, un-managed shared hosting to reliably process the file on potentially heavy customer demand, you’re rolling the dice.

TCPDF_PARSER ERROR: decodeFilterFlateDecode: invalid code

If you get this error, it is likely because you are trying to manipulate a PDF which has already been passworded or protected. PDFs must be unlocked with full user permissions in order to be parsed by TCPDI and watermarked. SetaPDF-Stamper can unlock PDFs prior to manipulation – if you provide an password in the PDF Ink settings for that PDF.

If you’re getting a different error message on the screen, please let us know right away! Use the information below about Error Logging in order to provide us information we need to help you. Everyone’s WordPress setup is different, so help us understand yours and how it might be interacting with PDF Ink.

FAQ

Why doesn’t the first page get stamped?

If PDF Ink is skipping the first page, maybe the parser (TCPDI or FPDI) is not reading that page as part of the document. Is it possible the cover page was added as an afterthought to an existing PDF? That’s called an incremented PDF. TCPDF struggles with incremented PDFs. Upgrade your library!

Alternatively you can try to repair the PDF yourself. The cover page must be reintegrated into the PDF source code, and often this can be done by removing it, adding it back in, and saving the file as a PDF.

We recommend using a PDF viewer such as Apple Preview to delete the cover page, save, then drag and drop the cover page back into place from another open version of the same file, then ‘Export as PDF’ to save it. This should help smooth out any problematic PDF syntax issues. Unfortunately we know of no other PDF reader (Windows or Mac) that can help the way Preview does for syntactically-incorrect PDFs. If you know of one, please reach out.

Why does the stamp go off the page, create new pages, or change the box size?

Your content text string or image is too big or long for the page size! The PDF writer created a blank page trying to accommodate the overflowing text.

Try decreasing font size, adjusting margins smaller, adjusting rotation, or using the X and Y fine tuners smaller to move the content back onto the page. The built-in adjustments on the settings page ultimately allow for stamping on all document sizes. You may need to edit your content if it is too verbose.

Why does the PDF have extra white space (or other changes that aren’t intended)?

If you find the base PDF is different after it is manipulated, it’s quite possible the PDF reading library struggled with the PDF’s syntax (see “trouble PDFs” above). Either upgrade your PDF library, or attempt to repair the PDF.

Try re-saving the file with Apple Preview, or editing crop boxes/clip paths with Adobe Acrobat/Illustrator, then try again. Bottom line: your PDF must have reasonably predictable PDF syntax in order for a machine to be able to read it consistently across all applications. Upgrading to SetaPDF-Stamper can solve these issues because not only does it attempt to repair poor syntax, but at default it does not read the entire PDF into memory.

There are countless variations and interpretations of PDF syntax such that the application you use to view your PDF might show it differently than the next application.

A white border is added

This is basically the same as “extra white space”, above. White border/margin added to top of page (or other area). This is most often caused by a layer in the PDF the original designer was either unaware of, or believed wouldn’t cause issues. It’s causing issues now. You can either try re-saving the PDF as described in the paragraph above, or opening the PDF with an editor such as Adobe Acrobat and finding/deleting the extraneous layer.

I get a bunch of blank pages

If you are encrypting your PDF and are getting all blank pages, your server might not support the encryption level you’ve chosen. This happens more often with AES encryption, so try RC4 instead. OpenSSL must be enabled on your host/server.