MaxtDesign

Troubleshooting

Previews Not Generating

This is the most common issue. The plugin needs ImageMagick to generate WebP previews.

Check Server Capabilities

  • 1.Go to Settings → PDF Viewer → Server Info
  • 2.Look for ImageMagick PHP Extension — should show "Available"
  • 3.If not available, contact your host to enable the ImageMagick PHP extension

    • Common Hosting Notes

  • SiteGround, Kinsta, WP Engine — ImageMagick usually pre-installed
  • Shared hosting — May need to request ImageMagick via support ticket
  • Docker/local dev — Install php-imagick package

    • Without ImageMagick

    The plugin still works — PDFs can be viewed in the full PDF.js viewer. You just won't get the instant WebP preview images. A generic placeholder will show instead.

    Preview Quality Issues

    If previews look blurry or pixelated:

  • 1.Go to Settings → PDF Viewer
  • 2.Change Preview Quality to High (300 DPI)
  • 3.Go to Tools tab → Process Unprocessed PDFs to regenerate
  • 4.Note: High quality creates larger preview files

    • Viewer Not Loading on Click

  • 1.Check browser console (F12) for JavaScript errors
  • 2.Verify the PDF URL is accessible (not behind authentication)
  • 3.Clear all caches (site cache, CDN, browser)
  • 4.Try a different browser to rule out extensions
  • 5.Check if another plugin is blocking JavaScript loading

    • Layout Shift (CLS) Issues

    If you're seeing layout jump when the viewer loads:

  • 1.Ensure the PDF was processed (preview generated) — the aspect ratio comes from the PDF metadata
  • 2.If the PDF wasn't processed, go to Tools → Process Unprocessed PDFs
  • 3.Check that no CSS is overriding the viewer's aspect-ratio property

    • Shortcode Not Working

  • 1.Verify the syntax: [pdf_viewer id="123"]
  • 2.Ensure the id is a valid PDF attachment ID (not a page/post ID)
  • 3.Check that the PDF exists in your Media Library
  • 4.The shortcode won't work in widget titles — only in content areas

    • Block Not Appearing in Editor

  • 1.Ensure the plugin is activated
  • 2.Search for "PDF" or "PDF Viewer" in the block inserter
  • 3.The block is in the Embed category
  • 4.Try clearing your browser cache and refreshing the editor

    • Large PDFs Loading Slowly

    For PDFs with many pages:

  • The preview always loads instantly (single WebP image)
  • The full viewer streams pages as needed — only visible pages render
  • Consider using "click" load behavior so the viewer doesn't load until requested
  • If the PDF file itself is large (50MB+), consider compressing it before upload

    • PHP Version Error

    The plugin requires PHP 8.1 or higher. If you see a version error:

  • 1.Check your PHP version: Tools → Site Health → Info → Server
  • 2.Contact your host to upgrade PHP
  • 3.Most hosts support PHP 8.1+ on current plans

    • Getting Support

    Use the [WordPress.org support forum](https://wordpress.org/support/plugin/maxtdesign-pdf-viewer/):

  • 1.Describe the issue
  • 2.Include: WordPress version, PHP version, ImageMagick status
  • 3.Check Settings → PDF Viewer → Server Info and include the details
  • 4.Attach a screenshot if it's a display issue
    • Developer Guide