Your Moodle Course Will Never Complete: The Empty-Criteria Trap

The mechanism

Why can completion be enabled and still impossible?

Course completion in Moodle is a chain of four parts, and the settings page only shows you the first one clearly:

1. enablecompletion on the course — the power switch. This is what "Enable completion tracking: Yes" sets.
2. mdl_course_completion_criteria — one row per condition that must be met: this activity completed, this grade reached, this many days enrolled. These are the checkboxes on the Course completion settings page, and none of them are checked by default.
3. mdl_course_completion_aggr_methd — how the criteria combine: ALL of them, or ANY.
4. The completion cron task, which evaluates the criteria per learner and writes timecompleted into mdl_course_completions.

The switch powers the chain. The criteria are the chain. With zero rows in the criteria table, the cron task has a list of zero conditions to check, checks all zero of them, and marks nobody — because "complete" is defined as "all criteria satisfied" and there are no criteria to satisfy. An empty rule set does not mean "everyone completes." It means the evaluation never produces a completion at all.

How do courses end up here? Easily. The Course completion page is a separate screen most people never open — enabling tracking in the course settings feels like the whole job. Courses restored from backup, duplicated, or created through web services routinely land with the flag on and the criteria table empty. Nobody notices until someone asks where the certificates are.

Honesty section: we did not find this on the first pass. We spent it on the certificate activity, which had two genuine faults of its own — it was restricted to membership of a group that had no members in it, and the course holding it was hidden. Both real, both worth fixing, and fixing both changed nothing, because upstream the member courses could never complete in the first place. Stacked faults are normal in inherited Moodle sites. Fix the chain from the source down.

The fix

How do I add the missing completion criteria?

For a single course, use the UI and go home early: Course completion settings, tick the activities that should count, add a grade condition if you want one, save, done. No script beats a checkbox for one course.

The scripted version is for when the fault is plural — we had a whole program of member courses to repair identically. Per course, the pattern is: one ACTIVITY criterion for each completion-enabled module, plus a GRADE criterion, aggregated ALL:

foreach ($mods as $cm) {
    $DB->insert_record('course_completion_criteria', (object)[
        'course'=>$cid, 'criteriatype'=>COMPLETION_CRITERIA_TYPE_ACTIVITY,
        'module'=>$cm->modname, 'moduleinstance'=>$cm->cmid ]);
}
$DB->insert_record('course_completion_criteria', (object)[
    'course'=>$cid, 'criteriatype'=>COMPLETION_CRITERIA_TYPE_GRADE,
    'gradepass'=>round($grademax*0.70, 5) ]);

foreach ([null, COMPLETION_CRITERIA_TYPE_ACTIVITY] as $ctype) {
    $DB->insert_record('course_completion_aggr_methd', (object)[
        'course'=>$cid, 'criteriatype'=>$ctype,
        'method'=>COMPLETION_AGGREGATION_ALL ]);
}
$DB->execute("UPDATE {course_completions} SET reaggregate=? WHERE course=?",
             [time(), $cid]);

Four things worth understanding rather than pasting blind:

• The ACTIVITY loop inserts one criterion per completion-enabled module — build $mods from the course's module list, keeping only modules whose own completion tracking is on. A criterion pointing at a module with tracking off can never be met, and you are back where you started.
• The GRADE criterion sets the course pass mark at 70% of the course grade maximum, rounded to 5 decimal places because that is the column's precision. Adjust the 0.70 to your program's actual bar.
• The aggregation rows are the part everyone forgets. Two rows: one with criteriatype NULL (the overall method) and one for the ACTIVITY type, both set to COMPLETION_AGGREGATION_ALL. Criteria without aggregation methods leave the evaluator undefined.
• The reaggregate update is what makes this fair to existing learners. Setting it to the current time flags every enrolment in the course for re-evaluation on the next completion cron run — against activity and grade data learners already have. Anyone who already did the work flips to complete without redoing anything.

Run it as a CLI script under the Moodle root so the COMPLETION_* constants and $DB are defined (require config.php, include lib/completionlib.php).

Then repair the downstream gates: change the certificate activity's restriction from the group condition to {"type":"coursecompleted"} so it is gated on completing its course, and unhide the course. All three locks off the door.

Gotchas

Why is a learner with a 90% average still incomplete?

Because of ALL aggregation meeting per-activity rules. In our program, each quiz had its own activity-completion rule of "complete on pass" with a 65% bar — and that sits under the course-level 70% grade criterion, as a separate condition. A learner can average 90% across the course and still be incomplete, because one quiz came in at 61% and its ACTIVITY criterion is therefore unmet. Two thresholds, evaluated independently, and the stricter interpretation always wins under ALL.

Our opinion: this is usually the behavior a certificate program actually wants — a certificate should mean every gate was cleared, not that the average papered over a failed module. But it must be the program's decision, not an accident. If it is not what you want, either relax the per-quiz pass rules or set the ACTIVITY aggregation row to ANY, and write down which you chose.

Two more edge cases from the same job:

• Hub courses cascade in order. A hub gated on member-course completion only moves after the member courses have reaggregated. Fix the members, let cron pass over them, then expect the hub — and its certificate — to follow on a subsequent run. If you check the hub five minutes after fixing the members, it will still look broken. It isn't. Give the chain time to propagate.
• Criteria are a snapshot, not a subscription. Adding a new activity to the course later does not add a criterion for it. If the course grows, revisit the Course completion page (or re-run the builder) or your completion definition quietly drifts away from the course content.

Quick answers

Questions people ask about this