Rank Math SEO Schema Warning: Missing Field “hasCourseInstance” on Custom Post Type

Root Cause Diagnosis

Rank Math’s Schema Generator validates output against Google’s structured data requirements, and Google’s Course rich result spec mandates that any Course type include a hasCourseInstance array describing at least one CourseInstance (with a courseMode set to online, onsite, or blended). When you apply the Course schema template to a custom post type through Rank Math’s Schema Generator or the “Schema Type” post meta box, Rank Math maps its default fields (name, description, provider) automatically but does not auto-populate hasCourseInstance, because that data doesn’t exist as a native WordPress field — it has to come from a custom field, ACF field, or a manually configured Schema Generator mapping. The warning fires because the generated JSON-LD is syntactically valid but incomplete against Google’s required-property list, not because of a plugin bug.

Quick Fix

Add a static hasCourseInstance block directly in Rank Math’s Schema Generator UI for the affected post type:

1. Go to Rank Math > Titles & Meta > [Custom Post Type] > Schema Type, or edit the individual post’s Schema tab.
2. Click Edit Schema on the Course template.
3. Locate the hasCourseInstance field and manually enter:

{
  "@type": "CourseInstance",
  "courseMode": "online",
  "startDate": "2026-09-01",
  "endDate": "2026-12-15"
}

This clears the warning for that individual post immediately. For a permanent, scalable fix across the whole post type, continue below.

Step-by-Step Resolution

1. Confirm which fields hold course date/mode data on your custom post type.

Check your CPT registration (commonly in functions.php or a custom plugin file) or your ACF/Meta Box field group to identify the meta keys storing course start date, end date, and delivery mode. Example ACF field names: course_start_date, course_end_date, course_delivery_mode.

2. Open Rank Math’s Schema Generator for the post type template, not the per-post editor, so the mapping applies to every post created under that type:

Rank Math > Titles & Meta > Post Types > [Your CPT] > Schema Type: Course

3. Map the custom fields to schema properties using Rank Math’s variable syntax.

In the hasCourseInstance.courseMode field, instead of hardcoding a value, use a custom field variable if your fields are exposed via a custom meta:

%customfield(course_delivery_mode)%

Rank Math resolves %customfield()% variables from post meta keys at render time. If using Advanced Custom Fields, the meta key must match your ACF field name exactly, and the field must be set to save as post meta (default ACF behavior).

4. For startDate and endDate, map the same way:

%customfield(course_start_date)%

Ensure the stored date format matches ISO 8601 (YYYY-MM-DD) — Rank Math does not reformat date strings before output, so a field storing 09/01/2026 will produce invalid schema even though the warning about the missing field disappears.

5. If your CPT has no per-instance dates (e.g., an always-available self-paced course), use eventAttendanceMode-style static values instead of trying to map nonexistent fields:

"hasCourseInstance": {
  "@type": "CourseInstance",
  "courseMode": "online"
}

Google accepts a CourseInstance without startDate/endDate as long as courseMode is present.

6. Validate the fix with Rank Math’s built-in tester before relying on Google’s crawler:

Rank Math > Status & Tools > Schema Validator, or paste a live post URL into Google’s Rich Results Test (search.google.com/test/rich-results).

7. Bulk-apply to existing published posts.

Schema Generator template changes apply automatically to schema rendered on page load, so no database migration is needed — existing posts pick up the new mapping the next time the page is requested (or cache is cleared, see below).

8. Purge cache.

If using a page cache plugin (WP Rocket, LiteSpeed Cache, W3 Total Cache) or a CDN, purge cached HTML for affected post type archives and single posts — cached pages will continue serving the old JSON-LD with the missing field until purged.

wp cache flush
wp rocket clean --confirm

Why This Fails for Some Users

• ACF Pro field groups scoped to the wrong post type: if the ACF field group’s location rules don’t explicitly include the custom post type, the field won’t save data for that CPT, and %customfield()% resolves to an empty string — the warning persists even after mapping.
• Custom post types registered with 'custom-fields' => false: some CPT registrations disable the native custom fields UI, meaning meta values are set only programmatically. In this case, %customfield()% still works if the meta key exists in the database, but you cannot verify or edit values through the standard WordPress meta box — use wp post meta get <post_id> <key> via WP-CLI to confirm the value is actually stored.
• Multisite installs with network-activated Rank Math: Schema Generator templates are saved per-site, not network-wide; a template configured on the main site does not propagate to subsites, so each subsite’s CPT needs the mapping repeated.
• REST API / headless WordPress setups (e.g., with Next.js or Gatsby frontends): if the frontend doesn’t render through WordPress’s wp_head(), Rank Math’s schema output is skipped entirely regardless of configuration — schema must be injected manually via the REST API’s exposed meta or Rank Math’s REST endpoints.
• Date fields stored as Unix timestamps rather than strings: some custom field setups (particularly Meta Box’s date picker with “timestamp” return format) store integers, which render as raw numbers in JSON-LD instead of ISO 8601 strings, causing Google’s validator to flag startDate/endDate as malformed even after the “missing field” warning clears.
• Rank Math Free vs. Pro field limits: the free version’s Schema Generator restricts which custom fields can be mapped to certain schema types; hasCourseInstance sub-properties are fully editable only when the Schema Generator’s advanced field mapping is available, which on some installs requires Rank Math Pro.