Applies to core 0.1.2 and Pro 0.1.0.
Start With System and Product Health
Media Sentry > System separates conditions needing investigation from informational generated derivatives. Inspect schema/table and uploads checks, scan details, unregistered files, and missing physical files. Use the available System Health export for external review. It does not perform a broad automatic repair or cleanup.
Product Health reports product image coverage and issues involving featured, gallery, and variation images, duplicates, and oversized images. Inspect the product and its references before editing it in WooCommerce. The report does not automatically assign, optimize, or repair product images.
Common Problems
| Symptom | What to check and do |
|---|---|
| Media Sentry menu absent | Confirm the free plugin is active and your account has manage_options |
| Empty or stale results | Finish Setup Baseline; inspect batch dates and rerun dependent steps after a refresh |
| Asset not found in latest scan | Return to the current results and locate the asset again; avoid reusing stale asset IDs |
| Missing tables or schema mismatch | Back up, confirm the installed package and activation completed, and involve the administrator if upgrade setup failed; do not manually drop tables |
| Uploads unreadable or unwritable | Ask the host to correct ownership and access for the PHP process; do not broadly grant public write access |
| Baseline or action batch stops progressing | Check WordPress cron execution, host loopback access, PHP errors, and rate limiting; inspect saved status before submitting more work |
| An active quarantine batch blocks another | Let it finish or resolve its worker failure, then review the remaining candidates |
| Quarantine Failed | Read the item's error, correct the cause, then use Retry Quarantine or Reset to Needs Review |
| Stale Approved for Quarantine | Inspect Quarantine Requests Needing Action; use Reset Stale Approvals to Needs Review when the old request should be reviewed again |
| Hash does not match | Preserve the file, investigate why it changed, and refresh inventory/duplicate evidence before reconsidering it; do not bypass validation |
| No longer eligible | Review current references, protection, and classification; reset or investigate rather than forcing cleanup |
| Restore destination exists | Preserve and compare both files; Restore will not overwrite the destination |
| Missing file or preview | Check the original path, quarantine state, and backup; a missing preview does not establish unused status |
| Similar Images empty | Confirm GD and image decoding support; exact duplicates and visual similarity are different tests |
| Pro cleanup unavailable | Confirm compatible core and Pro are active; activation setup is release-dependent. Maintenance expiry alone must not revoke installed Pro functionality |
| Retention expired but file remains | Expected: deletion requires a deliberate eligible-delete action and DELETE confirmation |
WP-CLI can inspect a batch and explicitly process queued items; see CLI reference. Inspect the batch first: continuing a delete batch carries out already requested permanent deletion. Do not run processing concurrently with another worker merely to speed it up.
Information for Support
Collect the core and Pro versions, WordPress/PHP versions, approximate image count, the affected workflow, scan or action batch ID, exact error, and whether a recent migration or media change occurred. Include the relevant System export or wp lf media doctor --format=json output, plus narrowly relevant server log entries.
Use Support as the primary contact. You can also email [email protected].
Review diagnostic files before sharing. They can contain filesystem paths, attachment IDs, content titles, and site details. Never send license keys, access tokens, credentials, or a complete production database as routine troubleshooting evidence.