[Bug][4.0.5] Fatal error in update_instructor_capability() when tutor_instructor role is missing

[vmtony]

Summary

Tutor LMS 4.0.5 causes a fatal error on every WordPress request when get_role( tutor()->instructor_role ) returns null.

The issue occurs in Tutor::update_instructor_capability(), which calls $role->has_cap() without checking whether the role exists.

Environment

• Tutor LMS: 4.0.5
• WordPress: 7.0.4
• PHP: 8.3.33
• Existing installation where Tutor LMS had not yet been configured or used

Observed conditions

• The tutor_instructor role was not present.
• tutor_removed_edit_other_items_permission was false or absent, so the new capability migration ran.
• Loading any WordPress endpoint triggered the fatal error, including the frontend, wp-login.php, and wp-admin/.

Error

Uncaught Error: Call to a member function has_cap() on null
in wp-content/plugins/tutor/classes/Tutor.php:1452

Stack trace:
#0 wp-includes/class-wp-hook.php: TUTOR\Tutor->update_instructor_capability()
#1 wp-includes/plugin.php: WP_Hook->do_action()
#2 wp-settings.php: do_action()
#3 wp-config.php
#4 wp-load.php
#5 wp-login.php

The site returned HTTP 500 on all tested WordPress endpoints until Tutor LMS was deactivated through WordPress Recovery Mode.

Root cause

Tutor LMS 4.0.5 added this logic:

$role = get_role( tutor()->instructor_role );

foreach ( $cap_to_be_removed as $cap ) {
    if ( $role->has_cap( $cap ) ) {
        $role->remove_cap( $cap );
    }
}

WordPress documents that get_role() returns WP_Role|null; therefore, the returned value must be checked before calling has_cap():

https://developer.wordpress.org/reference/functions/get_role/

The relevant Tutor LMS commits appear to be:

• Initial capability change: 95665d2
• Refactor into update_instructor_capability(): 8473b13

Expected behavior

Tutor LMS should not cause a fatal error when the instructor role is missing.

The capability migration should either:

1. safely recreate/repair the expected instructor role; or
2. return without marking the migration complete until a valid WP_Role object exists.

For example:

$role = get_role( tutor()->instructor_role );

if ( ! $role instanceof \WP_Role ) {
    return;
}

The option tutor_removed_edit_other_items_permission should only be updated after the role exists and the intended capabilities have been processed.

Current workaround

Tutor LMS 4.0.5 remains deactivated. No plugin files or course data were deleted.

Please confirm whether the plugin should automatically recreate the missing tutor_instructor role and include a defensive fix in the next release.

[maurosotok]

Hi @vmtony ,

I’m not a Tutor LMS developer, but I completed this on my site and it worked.

I was facing the exact same issue:

Uncaught Error: Call to a member function has_cap() on null
/tutor/classes/Tutor.php:1455

In my case, the issue was that the Tutor LMS role tutor_instructor did not exist, so Tutor was trying to call has_cap() on a null role.

I would recommend testing this on staging and having a backup before making changes. (Personally, I synced production to staging so we can apply a merge sync and apply the patch automatically)

1. Start Recovery Mode and access SSH

First, check whether the Tutor instructor role exists:

wp role list

Look for:

Tutor Instructor tutor_instructor

In my case, tutor_instructor was completely missing.

You can also check it directly:

wp eval '$r=get_role("tutor_instructor"); var_dump($r instanceof WP_Role);'

If the role is missing, you should get:

bool(false)
2. Create a temporary MU plugin

Create the MU plugins directory if necessary and add a temporary repair:

mkdir -p /srv/htdocs/wp-content/mu-plugins && printf '%s\n' '<?php add_action("init",function(){if(class_exists("\TUTOR\Tutor")&&!get_role("tutor_instructor")){error_log("TUTOR REPAIR: tutor_instructor missing. Recreating Tutor roles.");\TUTOR\Tutor::manage_tutor_roles_and_permissions();$role=get_role("tutor_instructor");error_log("TUTOR REPAIR RESULT: ".($role instanceof \WP_Role?"SUCCESS":"FAILED"));}},0);' > /srv/htdocs/wp-content/mu-plugins/tutor-role-repair.php

Then verify the file exists:

cat /srv/htdocs/wp-content/mu-plugins/tutor-role-repair.php

3. Check Tutor LMS status

Run:

wp --skip-plugins plugin status tutor

In my case Tutor LMS was inactive because I was working through Recovery Mode.

I also checked whether the Tutor class was loaded:

wp eval 'echo class_exists("\TUTOR\Tutor") ? "TUTOR CLASS LOADED\n" : "TUTOR CLASS NOT LOADED\n";'

Before activating Tutor, mine returned:

TUTOR CLASS NOT LOADED

4. Activate Tutor LMS

Run:

wp plugin activate tutor

Mine returned:

Plugin 'tutor' activated.
Success: Activated 1 of 1 plugins.

5. Check whether Tutor recreated the missing role

Run:

wp role list | grep tutor_instructor

After the repair, mine returned:

Tutor Instructor tutor_instructor

Then verify that WordPress can actually retrieve it as a role object:

wp eval '$r=get_role("tutor_instructor"); echo ($r instanceof WP_Role ? "ROLE OK\n" : "ROLE MISSING\n");'

Mine returned:

ROLE OK

6. Verify the Tutor capability migrations

I also checked these two options:

wp option get tutor_removed_edit_other_items_permission

and:

wp option get tutor_removed_read_private_items_permission

Both returned:

1

Before repairing the role, these options did not exist on my installation.

You can also inspect the capabilities assigned to the repaired role:

wp cap list tutor_instructor

The role should have Tutor capabilities. It should not be an empty role.

7. Resume Tutor and exit Recovery Mode

Once the role existed and the CLI checks were successful, I resumed Tutor LMS from the WordPress Plugins screen and exited Recovery Mode.

The site then loaded normally without the Tutor.php:1455 fatal error.

I tested the homepage, WordPress admin, login, REST API, Tutor dashboard, existing courses, and course lessons.

8. Remove the temporary MU repair

Once everything is working correctly, remove the temporary file:

rm /srv/htdocs/wp-content/mu-plugins/tutor-role-repair.php

Verify that it is gone:

test ! -f /srv/htdocs/wp-content/mu-plugins/tutor-role-repair.php && echo "Repair file removed"

Then verify one more time that the role persisted without the temporary repair:

wp eval '$r=get_role("tutor_instructor"); echo ($r instanceof WP_Role ? "ROLE OK\n" : "ROLE MISSING\n");'

It should still return:

ROLE OK

Finally, test the site again after removing the MU plugin.

In my case, this permanently resolved the issue because Tutor LMS recreated its missing tutor_instructor role and completed the capability migrations.