Troubleshooting Common Complianz mPDF Errors: Proof of Consent & File Generation Issues

Many users of the 'Complianz – GDPR/CCPA Cookie Consent' plugin encounter errors related to its mPDF library, which is responsible for generating Proof of Consent PDF documents. These errors often manifest as fatal errors or warnings in server logs, preventing the plugin from creating necessary files. This guide will help you understand and resolve the most common mPDF-related issues.

Common Error Messages

Based on community reports, the most frequent errors include:

• Fatal error: Uncaught MpdfMpdfException: Unable to create output file – The plugin cannot write the PDF to the specified directory.
• MpdfException: mbstring extension with mbregex support must be loaded – A required PHP extension is missing on the server.
• Warnings about undefined array keys, unserialize(), or font files – Often related to file permissions or server configuration.
• Errors mentioning temporary directories or fonts when using external storage (like S3 buckets) – The mPDF library struggles with non-standard filesystem setups.

Why These Errors Occur

The mPDF library within Complianz requires specific server conditions to function correctly:

1. File Permissions: The web server must have write permissions to the wp-content/uploads/complianz/ directory and its subfolders (especially snapshots/ and tmp/).
2. PHP Extensions: The mbstring PHP extension with mbregex support is mandatory for mPDF.
3. Server Configuration: Certain hosting environments, particularly those with external object storage (e.g., S3) for uploads, can interfere with mPDF's need to create temporary files locally.
4. Character Encoding: Using non-ASCII characters (like Greek or Cyrillic) in filenames can sometimes cause issues, though this is less common.

Step-by-Step Troubleshooting Guide

1. Verify and Fix File Permissions

The most common fix for "Unable to create output file" errors is ensuring the uploads directory is writable.

• Using an FTP client or your hosting file manager, navigate to wp-content/uploads/.
• Ensure the complianz folder exists. If it doesn't, create it.
• Inside the complianz folder, create a subfolder named snapshots.
• Set the permissions (CHMOD) for both the complianz and snapshots folders to 755 or 775. If issues persist, try 777 temporarily to test, but revert to a more secure permission afterward.

2. Install the Required PHP Extension

To resolve the "mbstring extension... must be loaded" error:

• Contact your web hosting provider.
• Request that they enable the mbstring PHP extension for your account. This is usually done through the hosting control panel (e.g., cPanel) or by modifying the php.ini file.
• Ask them to also ensure mbregex support is enabled within the mbstring extension.
• After they enable it, restart your web server (e.g., Apache or Nginx) for the changes to take effect.

3. Check for Conflicting Plugins or Storage

If you use a plugin that offloads media to external storage (e.g., S3):

• mPDF requires a local, writable temporary directory. These plugins can sometimes prevent mPDF from creating its necessary temporary files.
• Temporarily disable any media offloading/CDN plugins and test if the PDF generation works. If it does, you may need to configure an exception for the Complianz directories or seek an alternative setup. The 'Complianz – GDPR/CCPA Cookie Consent' team has previously suggested using the cmplz_mpdf_args filter to customize mPDF's arguments, which could help in such advanced scenarios.

4. Enable Debugging to Get Detailed Errors

If your error message is vague, enable WordPress debugging to get more information:

1. Edit your wp-config.php file (always back it up first).
2. Find the line define('WP_DEBUG', false); and change it to:

   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('WP_DEBUG_DISPLAY', false);
   

3. Save the file and reproduce the error by trying to generate a Proof of Consent snapshot.
4. Check the wp-content/debug.log file for a detailed error message, which can provide more specific clues.
5. Remember to disable debugging afterward by setting WP_DEBUG back to false.

When to Seek Further Help

If the steps above do not resolve your issue, the problem might be more complex and specific to your server environment. When seeking help from the community or your host, be prepared to provide:

• The full and exact error message from your logs.
• Your PHP version.
• The version of the Complianz plugin you are using.
• A description of your hosting environment (e.g., standard shared hosting, VPS, cloud platform with external storage).

By systematically checking these common points of failure, most users can successfully resolve mPDF errors and allow the Complianz plugin to generate its important Proof of Consent documents without issues.