Troubleshooting

This page covers the problems people most often hit with Dantian Course Cadence. Each one is set out as symptom → cause → fix, and quotes the exact message the plugin shows, so you can search this page for the wording on your screen.

Most fixes need a WordPress Administrator (anyone with the manage_options capability). Trainers and students should pass problems to their course administrator. Admin menu paths below all start from Course Cadence in the WordPress admin menu.

Before you start: three quick checks

1. Tools → Site Health → Status. The plugin adds three checks there. Look for any of these:
   • “No supported LMS active” — the LMS the plugin was using is no longer active.
   • “Course Cadence database tables are missing” — lists the missing tables.
   • “Course Cadence weekly email cron is not scheduled” — the weekly dispatch has no scheduled run.
2. Email Delivery → Send & Status → Weekly Dispatch Status. It shows the Next scheduled run (in your site timezone) and the Dispatch cooldown. “Not scheduled — reactivate the plugin to re-register the cron event.” means the weekly send isn’t scheduled.
3. Email Delivery → Test Emails. Send yourself a test. If the test doesn’t arrive, the problem is your site’s email delivery, not your timelines or prompts.

Emails not sending

Symptom: nobody received this week’s guidance email, or Email Delivery shows nothing sent.

Cause	How to tell	Fix
Your site can’t send email	A test from Email Delivery → Test Emails fails with “Failed to send email. Check your WordPress mail configuration.” (single course) or “Failed to send email. Check WordPress mail configuration.” (all courses), or reports success but never arrives	WordPress’s built-in mail is unreliable on many hosts. Install and configure an SMTP plugin, then set up SPF, DKIM and DMARC records for your sending domain. Send another test.
The dispatch hasn’t run yet	Next scheduled run is still in the future	Wait, or use Trigger weekly dispatch now (it asks you to confirm with Yes, send now).
Scheduled tasks aren’t running	Next scheduled run is in the past and nothing was sent	See Cron not running.
Nothing was due	Trigger weekly dispatch now reports “Dispatch ran — no emails were due right now. See the Analytics tab for delivery history.”	Check the course’s timeline and prompts (next rows).
No timeline covers today	Overview shows the course without an active timeline	A timeline is only active between its start and end dates. Create a timeline, or correct the dates, in Timelines & Prompts.
The timeline hasn’t started	Timeline start date is in the future	Nothing sends before the start date. This is expected.
No prompts for this week	The week has no prompts, or only trainer-only prompts	Add student prompts for the current week in Timelines & Prompts. Turn on the admin preview (Settings → Emails → Admin digest & alerts) to get a warning a few days before this happens.
A scheduled break covers today	Overview → This week, or the admin digest, lists the course as “Held for a scheduled break”	Expected — breaks hold that week’s email.
The course’s email delivery is paused	Overview → This week shows a Paused badge; the digest lists “Email dispatch paused”	See A course shows as Paused.

The plugin also won’t run the weekly dispatch twice within 23 hours. The Dispatch cooldown row shows “Active — set … ago, expires in ~…” while that window is open, and “Clear — next cron dispatch will proceed” once it has passed. Trigger weekly dispatch now clears the cooldown and runs straight away. Students who have already received a week’s prompts are not sent them again.

Some students got the email but others didn’t

Each weekly run sends up to 100 emails. On larger sites the rest wait for the next run, and those students then show as behind on the Overview. To send the remainder now, use Trigger weekly dispatch now on Email Delivery → Send & Status. People who already have this week’s guidance are skipped, so nobody gets a duplicate. Repeat until the run reports that no emails were due.

Some emails failed

Failed sends are recorded and retried automatically: once an hour, up to 25 failed emails are retried, and each email is retried up to 3 times. The Analytics tab on Email Delivery shows a red count badge while failures exist. If failures keep piling up, the cause is your mail setup — check your SMTP plugin’s log.

A student isn’t receiving emails

Symptom: most students are fine, but one person says they get nothing.

Work through these in order:

1. Spam or junk folder. Ask the student to check, and to add your sending address to their contacts.
2. Wrong email address. Check the address on their WordPress profile (Users → All Users).
3. They opted out. Students can switch off emails per course on the email preferences page. Ask them to open that page and switch the course back on. You’ll also see it if you try a manual catch-up: “[Name] has opted out of emails for this course.”
4. Not enrolled, or enrolment cancelled. Only current enrolments count. A cancelled Tutor LMS enrolment, or a student removed from a native class, gets nothing. Manual catch-up shows “[Name] is not enrolled in this course.”
5. They are an instructor. Instructors never receive student emails for the course they teach, and accounts with an LMS instructor role (or a Trainer in any native class) are left out of all student emails. Manual catch-up shows “[Name] is an instructor and cannot receive student catch-up emails.” Give the person a separate student account if they also need to study.
6. The course is paused or on a break. This affects every student in the course, not just one — see Emails not sending.
7. Rolling timeline, enrolled recently. On a Rolling timeline each student’s Week 1 starts on their own enrolment date and they receive the week matching where they are. A brand-new student receives their first email at the next weekly dispatch.

Wrong week number

Symptom: an email or the guidance page shows Week 4 when you expected Week 5 (or similar).

Cause	Fix
Week 1 starts on the timeline’s start date and each week is 7 days from there. It is not tied to the dispatch day. If the timeline starts on a Wednesday and emails go out on Mondays, a Monday falls part-way through a week.	Set the timeline start date to the same weekday as your dispatch day (or the day before).
Break days don’t count towards the week number. A one-week break holds the week count, so the week after the break carries on from where it stopped.	Expected. The student page shows “Scheduled break — no guidance this week. Week [N] resumes after the break.”
Rolling timelines count from each student’s enrolment date, not the timeline start date.	Expected. Two students in the same course can be on different weeks.
Site timezone is wrong. The dispatch time, today’s date and week boundaries all use the timezone in Settings → General.	Set the correct city-based timezone, e.g. “Melbourne” rather than a UTC offset, so daylight saving is handled.
The timeline dates were changed. Week numbers are always worked out from the current dates.	Expected. Guidance already sent isn’t resent.
Test email shows an unexpected week. The week in a test comes from the Test Date you chose.	Pick a test date that falls in the week you want to check. A Rolling test uses the selected student’s enrolment date.

On the last day of a Fixed period timeline, the guidance page shows the final week (for example “Week 12 of 12”) rather than going past the end.

A course shows as Paused

Symptom: Overview → This week shows a Paused badge on a course, and the digest or preview lists it under “Email dispatch paused”.

Cause: the course’s timeline has its email delivery paused. While paused, the weekly dispatch skips that course entirely (students and trainers). The guidance page still works, and catch-up emails for new enrolments are not held back by the pause.

Fix: version 1.0.0 has no pause/resume button on the admin screens. The setting is stored on the timeline and can only be changed through the plugin’s REST API by an administrator, so ask your site developer to unpause it. If you need to stop a course’s weekly emails yourself, alternatives are: adding a break period to the timeline for the weeks concerned, or temporarily removing that week’s prompts.

The student page shows a notice instead of guidance

The [dcc_student] shortcode shows a notice instead of guidance when something is missing:

Message	Cause	Fix
“Please log in to view your guidance.”	Not logged in	Log in with the Log in to view your guidance button. You’ll come back to the same page.
“You are not enrolled in any courses.”	Logged in but not enrolled in any course	Enrol the user in your LMS, or add them to a class as a Student.
“You are not enrolled in this course.”	The page or link points at a course the user isn’t enrolled in	Enrol them, or use a page without a fixed course_id.
“Course ID [N] not found.”	The course_id on the page doesn’t match a course (for example, the course was deleted, or a Tutor LMS ID is used in Native Classes mode)	Fix the course_id, or remove it so the page shows all enrolled courses.
“Guidance for this course begins on [date].”	The timeline starts in the future	Expected until the start date.
“No active timeline is configured for this course.”	No timeline covers today (none created, or it has ended)	Create a timeline, or adjust the dates, in Timelines & Prompts.
“Guidance for this week is not available yet.”	No student prompts for this week	Add prompts for the week.
“You have reached the end of this course. Use the week navigation above to revisit any past week’s guidance.”	The Fixed period timeline is in its final week and has nothing more to show	Expected.
“No guidance available at this time.”	None of the student’s enrolled courses has guidance to show	Check each course’s timeline and prompts.
The literal text [dcc_student] (or an old [tutor_guidance_…] tag) appears on the page	The plugin is inactive, or the page still uses an old shortcode name	Activate the plugin, and replace old tags with [dcc_student], [dcc_trainer_edit] or [dcc_email_prefs].

The email preferences page shows “Please log in to manage your email preferences.” to logged-out visitors and “You are not enrolled in any courses.” to users with no enrolments (including trainers who aren’t enrolled as students). See Shortcode reference.

A trainer can’t open the trainer page or suggest edits

Message or symptom	Cause	Fix
“Please log in to access the trainer interface.”	Not logged in	Log in.
“You are not assigned as a trainer to any courses.”	The user isn’t an instructor of any course	Assign them as an instructor in Tutor LMS or LifterLMS, or add them to the class as a Trainer on Classes.
“Only assigned trainers can access this interface.”	They opened a course they don’t instruct	Assign them to that course, or send them the right link.
“No active timeline configured for this course. Please set up a timeline in the admin area first.” / “The timeline for this course begins on [date].”	No current timeline	Create or correct the timeline.
The Suggest Edit button is greyed out with “Past weeks can’t be edited.”	The week is before the current week	Expected — past weeks are locked.
The Suggest Edit button is greyed out with “This week has already been sent and can’t be edited.” (week shows “Locked – Emails Sent”)	Guidance for that week has already gone out	Expected. An administrator can still change the prompt in Timelines & Prompts.
“All fields are required.” / “Subject is required.” / “Body is required.” / “Please provide a reason for this change.”	A field in the suggestion form is empty	Fill in the subject, body and reason.
“Only trainers assigned to this course can suggest edits.”	The trainer’s assignment was removed after they opened the page	Re-assign them, then reload the page.
“Failed to submit suggestion.”	The save failed (often a session that expired)	Reload the page and try again. If it keeps failing, log out and back in.
The week-by-week / multi-week choice isn’t remembered	The trainer’s account can’t edit posts (for example, a Subscriber)	The switch still works each visit; only the remembered preference needs Contributor-level access or higher.

Newly assigned trainers on Tutor LMS sites with a persistent object cache may need to wait up to two hours for access. See User roles and permissions.

Suggestions aren’t appearing in Pending Suggestions

• Auto-Approve is on. With Settings → Workflow → Trainer Edit Suggestions set to Auto-Approve, suggestions are applied straight away and never queue. The trainer sees “Your edit has been applied successfully!” and the change is recorded in the audit log.
• Nobody has submitted one. With Require Admin Approval, the trainer sees “Your edit suggestion has been submitted for review.” and the Pending Suggestions menu item shows a count.
• Notification emails not arriving. Check Settings → Workflow → Edit Notifications is ticked and Notification Recipients includes who you expect. Administrator notifications go to the site’s Administration Email Address (Settings → General).

Catch-up emails aren’t going out

Catch-up emails send missed weeks’ guidance to students who join late. See Catch-up emails.

Cause	Fix
It hasn’t been five minutes yet. Automatic catch-ups go out about 5 minutes after enrolment (Consolidated mode combines enrolments made within that window)	Wait, and make sure scheduled tasks are running (Cron not running).
Rolling timeline. Rolling timelines have no catch-up — each student starts at Week 1 from their own enrolment. Manual catch-up says “Catch-up emails are not available for rolling timelines. Each student progresses at their own pace from their enrolment date.”	Expected.
Nothing to catch up. The student joined in Week 1, or already has every past week. Manual catch-up says “No student prompts found up to week [N] for this course.”	Expected.
No current timeline. Manual catch-up says “No active timeline found for “[course]”.”	Create or correct the timeline.
Opted out, not enrolled, or an instructor	See A student isn’t receiving emails.
The enrolment didn’t trigger a catch-up. For example, students imported in bulk, or enrolled before a timeline existed	Use Overview → All courses: students behind appear under each course with Review & send, where you can Send catch-up or Dismiss. Or use Email Delivery → Send & Status → Send Manual Catch-up Email… for one student. Success reads “Catch-up email sent to [name] for “[course]” (up to week [N]).”

Cron not running

Symptom: the Next scheduled run is in the past, emails go out hours late, catch-ups never arrive, or Site Health reports “Course Cadence weekly email cron is not scheduled”.

Cause: the plugin relies on WordPress’s scheduled tasks (WP-Cron). By default WP-Cron only runs when someone visits the site, so a quiet site may not send at the set time. Some hosts disable WP-Cron (DISABLE_WP_CRON) without replacing it with a real server cron job. A cleanup plugin or a manual update by zip upload can also remove scheduled events.

Fix:

1. If Next scheduled run says “Not scheduled — reactivate the plugin to re-register the cron event.”, deactivate and reactivate Dantian Course Cadence on the Plugins screen. Saving the Settings → Schedule tab with a new day or time also reschedules it. The daily watchdog restores a missing weekly event on its own, too.
2. Set up a real server cron job that calls wp-cron.php every 5–15 minutes (ask your host), especially if DISABLE_WP_CRON is set.
3. Turn on Send Admin Trainer Digest (Settings → Emails → Admin digest & alerts) so you’re emailed “Course Cadence: the weekly guidance dispatch is late” if a weekly send runs more than a day late.
4. A tool such as the WP Crontrol plugin lets you see the plugin’s scheduled events, which all start with dantian_course_cadence_ (the weekly send is dantian_course_cadence_weekly_guidance_dispatch).

See Scheduled tasks and Site Health for every scheduled task and its timing.

Settings don’t seem to save

Symptom	Cause	Fix
Changes disappear after switching tabs	Each tab saves separately; switching tabs throws away unsaved changes	Click Save Settings on each tab before moving to the next. Look for “Settings saved.”
A number changed after saving	Values outside the allowed range are corrected: Log Retention Period is kept between 30 and 3650 days; Preview Days Before Dispatch between 0 and 6	Enter a value in range.
Day or time reverted to Monday / 09:00	An invalid day or time was entered	Pick from the dropdown and enter a valid 24-hour time.
An auto-detected page URL isn’t used in emails	Auto-detected URLs are only suggestions until saved	Click Save Settings on the Emails tab.
Digest Recipient Email went blank	The address wasn’t a valid email, so it was cleared — the site admin email is used instead	Enter a valid address.
An attachment domain vanished	Entries that aren’t plain domain names are dropped (a full URL is reduced to its domain)	Enter domains like files.example.edu.au, one per line.
Script or embed code removed from the template, intro or footer	Unsafe HTML is stripped for security	Use plain formatting and links only.
Single-Course Intro Line has no effect	A custom Email Template is in use, and it replaces the built-in intro	Edit the wording in the template, or clear the template completely to use the intro line. See Settings reference.

If you can’t see Course Cadence → Settings at all, your account doesn’t have the manage_options capability.

Test emails don’t show what you expect

• “No active timeline for this date” — the Test Date falls outside the timeline’s dates.
• “No student prompts found for week [N]” (or “No trainer prompts …”) — that week has no prompts for the chosen Email Type.
• “Student not enrolled in any courses” / “No prompts available for any enrolled courses on this date” — for Test All Courses Email, pick a student with current enrolments and a date with guidance.
• The test arrives but the layout or greeting is wrong — check Settings → Emails → Content & template, and see how the Email Template replaces the built-in greeting and intro.

Admin pages are blank or won’t load

1. Check the browser console (F12 → Console) for JavaScript errors.
2. Temporarily turn off caching, optimisation and minification plugins. Course Cadence’s admin screens use WordPress Script Modules, which some optimisers break.
3. Deactivate other plugins one at a time to find a conflict.
4. Confirm WordPress 6.7 or later and PHP 8.0 or later.
5. Re-upload the plugin from the official release zip if files may be missing (the build/ folder must be present).

Database tables missing

If Site Health reports “Course Cadence database tables are missing”:

1. Deactivate and reactivate the plugin — activation creates any missing tables.
2. If they still don’t appear, ask your host to confirm the database user can create tables.
3. Check your PHP error log for database errors during activation.

Getting debug detail

When WP_DEBUG and WP_DEBUG_LOG are both turned on in wp-config.php, the plugin writes errors and warnings to the WordPress debug log (wp-content/debug.log), each line starting with [DCC]. For example, “dispatch_weekly_emails — no eligible courses this week” shows how many courses were skipped for each reason. Turn debugging off again when you’re done.

Worked example: “Nobody got Monday’s email”

The coordinator at a community college clinic gets no Monday guidance emails for the “Clinical Placement Prep” cohort.

1. Email Delivery → Send & Status shows Next scheduled run as last Monday at 08:00 — it’s in the past, so scheduled tasks aren’t running.
2. Tools → Site Health is otherwise healthy. The host confirms DISABLE_WP_CRON is set with no server cron job. The coordinator asks the host to add a 5-minute cron job for wp-cron.php.
3. Back on Send & Status, the coordinator clicks Trigger weekly dispatch now, then Yes, send now. The result reads “42 emails sent. Covering 3 course-weeks. See the Analytics tab for the full breakdown.”
4. To catch this sooner next time, they tick Send Admin Trainer Digest on Settings → Emails so the late-dispatch warning reaches them.

Getting support

• Students: for questions about guidance content, contact your trainer. For problems logging in or receiving emails, contact your course administrator.
• Trainers: contact your course administrator about course assignments and suggestions.
• Administrators: see the FAQ, Settings reference and User roles and permissions. Report plugin problems through the plugin’s WordPress.org support forum.