PdfHandler Debugging

PdfHandler Troubleshooting: Restart Routine

When adjusting PdfHandler prerequisites (Entware binaries, PATH updates, or MediaWiki configuration), make sure to restart both WebStation and the MediaWiki package.

Steps

1. Verify prerequisites are installed and callable:

which gs
which pdftoppm
which magick

1. Restart **WebStation**:

Control Panel → Web Services → WebStation → Restart

1. Restart **MediaWiki package**:

Package Center → Installed → MediaWiki → Restart

1. Clear cached test files if needed:

rm /volume1/web/mediawiki/images/*.pdf
rm /volume1/web/mediawiki/images/thumb/*.pdf

1. Upload a fresh PDF and confirm thumbnails are generated.

Notes

• Restarting WebStation alone may not reload MediaWiki’s environment variables.
• Restarting MediaWiki ensures new PATH and handler settings are applied.
• Always document the rationale for successors: “Restart both packages after changes.”

Symptom	Likely Cause	Diagnostic Step	Fix / Routine
PDF upload shows no preview	Missing or mis-set `$wgPdfPostProcessor`	Check `LocalSettings.php` for correct binary path	Set to `magick` (ImageMagick v7) or `gs` (Ghostscript) as installed
Error: "open_basedir restriction"	DSM PHP configuration limits	Inspect `php.ini` and DSM Web Station settings	Add required paths to `open_basedir` or disable restriction for MediaWiki
PdfHandler fails silently	PATH not updated for Entware binaries	Run `which gs` / `which pdftoppm` via SSH	Update PATH in `LocalSettings.php` or DSM task scheduler
Wrong command syntax in `$wgPdfPostProcessor`	Dash or argument misconfiguration	Compare with PdfHandler documentation	Correct to `gs -q -dNOPAUSE -dBATCH ...` or `magick convert ...`
Preview works but thumbnails broken	ImageMagick vs Ghostscript mismatch	Test both processors manually	Standardize on one processor and document choice