Troubleshooting

Updated

Pro feature. Available in MediaShield Pro.

PRO - covers problems with MediaShield Pro features. For player and protection problems in the free plugin, use the free plugin's troubleshooting guide.

Find the symptom, read the cause, follow the fix. The messages quoted below are the exact words the plugin shows.

Before you start#

  • Check that the free MediaShield and MediaShield Pro are both active and on matching versions (1.4.0 with 1.4.0).
  • Turn on WP_DEBUG_LOG while you test. Several problems write to wp-content/debug.log.

Install and screens#

"MediaShield Pro requires the free MediaShield plugin to be installed and activated."#

Pro does not run alone. Install and activate the free plugin first, then Pro.

Pro screens (Platforms, Alerts, Heatmaps...) are missing from the MediaShield page#

  1. Confirm both plugins show Active.
  2. Hard-reload the MediaShield page. Pro's screens are added by a script that loads after the free one.
  3. Clear any page or object cache.

A card or box I expect is missing#

Several boxes appear only when something else exists:

Missing Appears only when
LMS Integration (video screen and Settings) LearnDash, Tutor LMS or LifterLMS is active
Video Ads box and Video Ad Defaults WB Ad Manager Pro supplies video ads
Upload & Storage card in Settings At least one platform is connected
"DRM - Encrypted playback" protection level DRM Method is not None

Platforms and imports#

"Bunny Stream validation failed: ..."#

Bunny refused the API Key or Library ID. Copy the API key from Bunny dashboard > Stream > API and the Library ID from the library settings again. Nothing was saved.

"A Pull Zone hostname ... is required to stream Bunny videos."#

Fill in Pull Zone Hostname (for example vz-12345-e25). The connection is refused without it.

The library browser says "No Connection Found"#

There is no active connection for that platform. Go to MediaShield > Platforms and connect it.

The YouTube library is empty#

A YouTube connection needs a Channel ID (starts with UC) to list videos. Disconnect, then connect again with the Channel ID.

Connections stopped working after a security change on the site#

Saved credentials are locked with your site's SECURE_AUTH_SALT. If the salts were regenerated, the plugin cannot read them ("Failed to decrypt Bunny Stream credentials"). Disconnect and connect again.

Import says "Failed to fetch video details" or "N failed to import"#

The platform did not return that video. Check the key still has the right permissions (Vimeo: public, private and video_files), the video is not private to another account, and try Refresh. Videos already imported are skipped and counted as "already imported".

A video imported but will not play#

For Bunny, the Pull Zone Hostname must match where the video streams from, and if your library uses token authentication, signing must be set up. See Play Bunny Videos in the MediaShield Player.

Bunny#

After turning on direct playback, the video box is black or loops#

Save the page again on MediaShield > Bunny Playback and read the test result. If the test fails, direct playback turns itself off. Common causes: the token authentication key is wrong or missing while the library requires one, or you chose MP4 but MP4 Fallback is off in Bunny. Switch back to HLS.

The video length stays 0 after uploading to Bunny#

Bunny has not told your site that encoding finished. Check the webhook:

  1. Copy the Webhook URL from the Bunny connection form and paste it into Bunny's library Webhook field. See Bunny Webhook.
  2. The site must be reachable from the internet. A local or password-protected site cannot receive it.
  3. A call without the secret is refused (403, invalid_signature). If you pasted an address without ms_token, paste the full one.

Uploads from Videos > Add New go to Bunny, not my server#

The Default Upload Target is Auto, which uses a connected platform. Set it to Self-hosted under MediaShield > Settings > Upload & Storage.

Encrypted streams#

"Your access to this video has been revoked."#

The viewer was revoked on the DRM screen for this video. The revoke is permanent through the screen. A developer must clear it in the database.

"Revoke All Licenses" reports 0 revoked#

The user had never requested a licence for that video, so there was nothing to revoke. Nothing is blocked.

Analytics#

The heatmap is empty#

  1. The video must record sessions (protection level Standard or Strict).
  2. Wait an hour. The chart is built hourly by Action Scheduler. Check Tools > Scheduled Actions for ms_heatmap_aggregation.
  3. Viewers must watch long enough for the player to report its position (about 30 seconds apart).

Realtime shows nobody while I am watching#

Realtime lists sessions with a heartbeat in the last 5 minutes. Make sure you are watching in the MediaShield player, logged in or with login not required, and that the video is not set to a level that records no session.

Alerts: nothing appears#

That is normal on a quiet site. Detection runs when sessions start. Multiple IP addresses needs several different addresses for one account inside the window (see Suspicious Activity and VPN Detection). Developer tools alerts need the free devtools detection setting on.

Alerts: too many Multiple IP addresses alerts#

Lower the sensitivity to Low. Keeping login required ties each alert to one named account.

Rapid seeking alerts for a student who simply resumed#

Resume jumps to a saved position. A viewer who resumes past 80 percent within 30 seconds looks like a rapid seek. Use Mark as Safe for staff, or ignore it.

"Detection is switched on but no API key is saved, so no lookups are being made."#

VPN detection needs an ip-api.com key. Add it on the Alerts page, or switch detection off.

The Alerts list does not say why something was flagged#

The explanatory sentence is saved but the list shows only type, user, video and time. To see the evidence, export Watch Sessions as a CSV and look at that user's IP addresses and times.

Export and digest#

"Action Scheduler is not available."#

PDF reports and the weekly digest need Action Scheduler. The free MediaShield plugin includes it. Reactivate the free plugin and check Tools > Scheduled Actions loads.

"Report generation timed out. Please try again."#

The background job did not finish while the screen was waiting. Open Tools > Scheduled Actions, look for mediashield_generate_pdf, and run it. A site with WP-Cron disabled and no real cron will not run jobs.

"Export job not found."#

The job ID is no longer in Action Scheduler (it was cleaned up). Generate a new report.

The CSV has a first row saying it is INCOMPLETE#

The Users export hit its 200,000 row ceiling. Narrow the dates and export again.

The weekly digest does not arrive#

  1. MediaShield > Export > Weekly Digest is switched on.
  2. The recipient address is valid, or empty (then it uses the admin address).
  3. Click Send Test Digest Now. If it says the digest is disabled, switch it on first.
  4. If the test arrives but the weekly one does not, check that ms_weekly_digest appears under Tools > Scheduled Actions, and that your site sends email.

Milestones and LMS#

A milestone action did not fire#

  • Guests never trigger milestones.
  • Each milestone fires once per viewer per video. A viewer who already passed it will not fire it again, even after you add the action.
  • A Send Email action with an empty subject is skipped.
  • A webhook that fails is not retried. Test with Test Fire, and read the HTTP status it reports.

The lesson did not complete#

  1. The video must be linked to the lesson (LMS Integration box).
  2. Auto-complete lessons must be on in Settings.
  3. The student must be logged in and reach the completion milestone. A setting of 90 completes at 100.
  4. The viewer must have passed the milestone for the first time since linking. Earlier completions do not re-fire.

Students are blocked with "You must be enrolled in this course to watch this video."#

The video has Require enrollment ticked and the student is not enrolled in the linked lesson's course. Untick it on the video, or switch the site-wide Require enrollment off.

The video shows twice on the lesson#

The lesson content already has a shortcode and the automatic placement was added too. MediaShield skips the automatic one when it sees [mediashield. If you use a page builder block that outputs the video, ask a developer to disable the automatic placement with the mediashield_pro_render_linked_lesson_video filter.

Video ads#

No ads play#

  1. WB Ad Manager Pro must be active with at least one enabled Video Ad.
  2. Enable In-Video Ads must be on (Free setting).
  3. The video must not be set to "No ads on this video".
  4. The video must play in the MediaShield player. A Bunny video needs direct playback.

Licence#

"Activation rejected: ..." or "Activation failed."#

See Activate Your Licence. Rejected means the store said no (expired, site limit). Failed means the request could not reach the store.

Still stuck?#

Check the FAQ, then contact support@wbcomdesigns.com with your versions, the exact message and what you clicked.