What this plugin is for
LearnDash sites accumulate structural debt. Courses get restructured and lessons come loose. A quiz is rebuilt and the old one is left attached to nothing. A group is created and nobody is made its leader. None of it produces an error message — it produces a learner who hits a wall, and an email you have to answer.
Health Check runs twelve structural checks across your LearnDash content and puts everything it finds on one screen, sorted by how much it matters.
The scan is read-only. Running it never changes anything. Cleanup exists, but it is opt-in, offered on four checks only, and moves items to the trash rather than deleting them.
Requirements
- WordPress 5.8 or later
- PHP 7.4 or later
- LearnDash LMS — the plugin does nothing without it and says so
- An administrator account (the screen requires
manage_options)
Installation
- Install the zip through Plugins → Add New → Upload Plugin, or upload the folder to
/wp-content/plugins/. - Activate it.
- Go to LearnDash LMS → Health Check. If LearnDash’s own menu is not present the screen appears under Tools → Health Check instead.
- Click Run health check.
Nothing is scanned until you ask. There is no scheduled job, no background queue and no database table — the plugin is inert until you press the button.
Reading the report
The bar at the top counts what was found, in three severities:
| Severity | What it means |
|---|---|
| Critical | A learner is being blocked or shown something broken right now. Fix these first. |
| Warning | Content is in a state you almost certainly did not intend. Nothing is on fire, but it is wrong. |
| Notice | Something worth confirming rather than fixing. A notice is often a deliberate choice — it is listed so the choice is visible. |
Below the counts, each check gets its own card with a coloured spine matching its severity. A check that found nothing is marked OK and still shown, so you can tell “this is fine” from “this was never checked”.
The twelve checks
| Check | Severity | What it means, and what to do |
|---|---|---|
| Courses with no content | Critical | The course has no lessons, topics or quizzes. Anyone who enrols opens it and finds nothing. Either build it out or unpublish it. |
| Orphaned lessons | Warning | A lesson that belongs to no course. Usually left behind when a course was deleted or restructured. Reattach it or trash it — cleanup is offered. |
| Orphaned topics | Warning | A topic attached to neither a course nor a lesson. Same cause, same fix. Cleanup is offered. |
| Orphaned quizzes | Warning | A quiz attached to nothing at all. Learners can never reach it. Cleanup is offered. |
| Quizzes with no questions | Critical | A quiz containing zero questions. It can be neither passed nor skipped, so on a course with linear progression it is a dead end. This is the single most common cause of “I’m stuck and I can’t continue”. |
| Questions not used in any quiz | Notice | Question posts no quiz references. Harmless, but they clutter the question bank and make it hard to find the ones in use. Cleanup is offered — review first, because drafts you intend to use look identical to leftovers. |
| Courses with no certificate | Notice | Only a problem if you meant to award one. Listed so you can confirm the omission is deliberate. |
| Groups with no group leader | Warning | Nobody can administer or report on the group. If you sell to organisations, this is the check that catches the account nobody can manage. |
| Groups with no courses | Notice | Membership of the group grants access to nothing. Sometimes deliberate — a group used purely for segmentation — and sometimes a setup that was never finished. |
| Steps pointing at a missing course | Critical | A lesson, topic or quiz whose parent course no longer exists or is in the trash. The association is broken and the step is unreachable. |
| Unpublished courses with enrolled users | Warning | People are enrolled in a course that is draft, pending or private. They are locked out of something they may well have paid for. |
| Broken course prerequisites | Critical | A course requires completion of a prerequisite that no longer exists or is unpublished. The condition can never be satisfied, so nobody can ever enter the course. |
Working through the results
Each check lists the items it found in a small table: the post ID, the title as a link to the editor, and a short explanation of what is wrong with that particular item. Clicking a title takes you straight to the thing that needs fixing.
Long lists are capped in the display — if a check finds more than 100 items you see the first 100 and a line telling you the true total. The cap is presentational only; cleanup still acts on everything the check found.
Cleanup, and why it is safe
Four checks offer a Move all to trash button: orphaned lessons, orphaned topics, orphaned quizzes, and unused questions. These are the only checks where “delete it” is a plausible answer, because in every case the content is attached to nothing.
Three things make this safe to use:
- It is never automatic. Nothing is cleaned up as a side effect of scanning. You have to press the button, and confirm.
- It trashes, it does not delete. Items go to the WordPress trash and can be restored from the normal Posts-style list screens.
- It acts only on what was just reported. The list on screen is the list that gets trashed.
The other eight checks deliberately offer no button, because the right fix is a judgement call — reattaching a step, publishing a course, appointing a group leader — and a plugin should not make it for you.
Checks that pass, and checks that are skipped
Two states are worth telling apart.
OK means the check ran and found nothing. That is a result you can trust.
Skipped means the check could not run because the LearnDash function it depends on does not exist in your version. Rather than fail, the plugin reports the skip and carries on, and a line under the severity counts tells you how many checks were skipped in total. This is what keeps the plugin from breaking when LearnDash changes: a check that no longer applies goes quiet instead of throwing an error.
Large sites
Each check examines up to 2,000 items per content type per run. On the great majority of LearnDash sites that is the whole library. On a site with more content than that, the scan still completes within normal PHP limits and reports on the first 2,000 of each type rather than timing out halfway through.
The scan runs in the request, so it is not something to leave running on a schedule — press the button when you want an answer.
For developers
Adding your own check
The check registry is filterable. Each entry needs a label, a severity, and a callback returning the affected items:
add_filter( 'rau_ldhc_checks', function ( $checks ) {
$checks['my_missing_video'] = array(
'label' => 'Lessons with no video URL',
'severity' => 'warning',
'callback' => 'my_find_lessons_without_video',
'desc' => 'These lessons were meant to carry a video and do not.',
);
return $checks;
} );Severity is one of critical, warning or notice. Adding 'cleanup' => true enables the trash button for your check — only do that when trashing is genuinely the right answer for everything the check can return.
The same filter removes checks. If “Courses with no certificate” is noise on your site because you do not use certificates:
add_filter( 'rau_ldhc_checks', function ( $checks ) {
unset( $checks['courses_no_certificate'] );
return $checks;
} );Troubleshooting
“Sorry, you are not allowed to access this page”
The screen requires the manage_options capability. Editors and group leaders cannot open it; an administrator can.
The menu item is not under LearnDash
The plugin attaches itself to LearnDash’s menu when that menu exists, and falls back to Tools when it does not. If the item is under Tools, LearnDash was not active when the menu was built.
A check reports items I have already fixed
The report is a snapshot of the moment you pressed the button — there is no cache. Click Re-run scan after making changes.
Everything shows as skipped
That means LearnDash is not providing the functions the checks call, which normally means LearnDash is not active. The plugin shows an admin notice in that case.
Frequently asked questions
Will this change or delete anything on my site?
Not on its own. Scanning is entirely read-only. The only write the plugin can perform is the cleanup you explicitly trigger, and that moves items to the trash.
Can I undo a cleanup?
Yes. Trashed lessons, topics, quizzes and questions appear in the Trash view of their own list screen in wp-admin and can be restored there.
Does it work alongside other LearnDash add-ons?
Yes. It reads LearnDash data and adds one admin screen. It does not filter or alter LearnDash behaviour, so it has nothing to conflict with.
Should I run this regularly?
Run it after any structural change — a course restructure, a bulk import, a migration — and before a launch. It is a diagnostic, not a monitor.
Does it slow my site down?
No. Nothing runs on the front end, and nothing runs in wp-admin except when you press the button.
Uninstalling
The plugin stores no options, creates no tables and schedules no jobs. Deactivating and deleting it removes it completely and leaves your LearnDash content exactly as it was.
