Basic WordPress Troubleshooting
When something goes wrong with WordPress, perform these basic troubleshooting steps before asking for help. Anyone can do basic troubleshooting. It 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:
- Switch to a default WordPress theme temporarily under WordPress -> Appearance -> Themes. A default WordPress theme is twentytwentythree, twentytwentyfive, etc. Now reload the page or perform the process again and check if the problem is still there. Is the problem still there? Then it’s not a conflict with your theme. Great sleuthing so far!
- Deactivate all plugins except for PDF Ink and (WooCommerce/Easy Digital Downloads/Download Monitor, if you are using one of those). Deactivate all of the others plugins 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 the problem still hasn’t re-appeared, switch back to your WordPress theme then repeat step 2 to rule out a theme+plugin 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
Start by making sure everything works without PDF Ink activated, and perform basic troubleshooting (above).
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.
- 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)! Some of the error messages are detailed on the “Error Messages” page.
- Make sure your uploaded PDF file is not already encrypted/passworded. Unless you are using SetaPDF-Stamper or FPDI PDF-Parser and have set the PDF 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.
- 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.
- 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.
- 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. It is entirely possible that a free application you are using to build PDF files is also including malware in them, or just writing them sloppily. They might look fine, but…
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 figure out if the problem is the PDF, or the software.
Secondly, re-saving a broken PDF with the Apple Preview application (“Export as PDF”) or Adobe Acrobat can sometimes help clean it up so PDF Ink can do its job. Somehow, Apple Preview (and Safari) just have excellent PDF reader/writers that can read funky PDFs and then (maybe) correct the syntax for you.
While you’re doing this, maybe also check your PDF for malware.
Third, try again with a different PDF Ink library. We know that the free libraries TCPDI and FPDI have their limitations, but one might work better than the other with your particular PDF. Limitations? Here are some examples: free FPDI doesn’t work with newer PDFs (version 1.5+) and TCPDI doesn’t seem to handle object references or objects where the values are split onto new lines (which we are seeing in some PDFs).
Finally, if you must must must stamp/password this PDF, and want full fidelity and zero headache, 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, 2 and 3 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.