WordPress Cron Jobs: How to Set Them Up and Fix Them When They Break

1. A visitor (or a bot, or Googlebot) loads any page on your site
2. WordPress processes the request and, near the end of execution, calls wp_cron()
3. wp_cron() checks the cron option in the WordPress database — a serialized array of all scheduled events and their next-run timestamps
4. If any events are overdue (their next-run timestamp is in the past), WordPress spawns a non-blocking HTTP request to yourdomain.com/wp-cron.php
5. wp-cron.php runs the overdue events in the background
6. The visitor’s page loads normally — they don’t wait for the cron jobs to finish

The critical implication of step 1: if no page is loaded, wp-cron.php is never called. A scheduled post set to publish at 3:00 AM will publish whenever the next page visit happens after 3:00 AM — which on a low-traffic blog might be 3:47 AM, or 9:15 AM, or not until the next day.

If your host provides WP-CLI access (Cloudways, Kinsta, SiteGround, and most managed hosts do), this is the fastest way to see everything:

# List all scheduled cron events
wp cron event list

# List events with next run time and recurrence
wp cron event list --fields=hook,next_run_relative,recurrence

# Run a specific event manually (useful for testing)
wp cron event run wp_update_plugins

# See all registered cron schedules (hourly, daily, etc.)
wp cron schedule list

# Delete a specific cron event
wp cron event delete hook_name

The --fields flag is useful for a clean overview. On a typical WordPress site, wp cron event list outputs 15–60 rows depending on your plugin stack.

WP Crontrol (free, 800k+ active installs) adds a Cron Events screen to your WordPress admin at Tools → Cron Events. It shows every scheduled event, its next run time, its recurrence, and the file/line that registered it.

Key things you can do in WP Crontrol:

• Run any cron event manually with one click — essential for testing whether an event actually works
• Delete orphaned cron events left behind by uninstalled plugins
• Add custom cron events without writing code
• See exactly which plugin registered each event — by filename and function name
• Edit the schedule of any existing event

/* Disable WP-Cron — replaced by real server cron job */
define( 'DISABLE_WP_CRON', true );

/* That's all, stop editing! Happy publishing. */

This tells WordPress to stop spawning HTTP requests to wp-cron.php on every page load. Your scheduled tasks will not run until you complete Step 2 — so set up the server cron job before or immediately after adding this line.

/**
 * Schedule a custom cron event on plugin/theme activation.
 * This registers the event only once — wp_next_scheduled prevents
 * duplicate registrations on subsequent page loads.
 */
function toptut_schedule_my_task() {
    if ( ! wp_next_scheduled( 'toptut_my_custom_event' ) ) {
        wp_schedule_event(
            time(),                  // Start time (Unix timestamp)
            'hourly',               // Recurrence: hourly, twicedaily, daily, weekly
            'toptut_my_custom_event' // Hook name — must be unique
        );
    }
}
add_action( 'wp', 'toptut_schedule_my_task' );


/**
 * Hook your actual function to the cron event.
 * This is what runs when the scheduled event fires.
 */
function toptut_my_task_callback() {
    // Your code here — e.g. send an email, process a queue, clean a table
    error_log( 'toptut_my_custom_event fired at: ' . current_time( 'mysql' ) );
}
add_action( 'toptut_my_custom_event', 'toptut_my_task_callback' );


/**
 * Clean up on plugin/theme deactivation.
 * Always remove your cron events when your plugin is deactivated —
 * orphaned cron events accumulate in the database otherwise.
 */
function toptut_deactivate_my_task() {
    $timestamp = wp_next_scheduled( 'toptut_my_custom_event' );
    wp_unschedule_event( $timestamp, 'toptut_my_custom_event' );
}
register_deactivation_hook( __FILE__, 'toptut_deactivate_my_task' );

The three most common mistakes when registering custom cron events:

• Missing the wp_next_scheduled check — without it, every page load registers a new copy of the event, leading to hundreds of duplicate entries in the cron table
• Not cleaning up on deactivation — orphaned events from uninstalled plugins accumulate and waste execution time on every cron run
• Using a non-unique hook name — if two plugins register events with the same hook name, they will interfere with each other

function toptut_add_cron_intervals( $schedules ) {

    // Every 5 minutes
    $schedules['every_five_minutes'] = array(
        'interval' => 5 * 60,
        'display'  => __( 'Every 5 Minutes' ),
    );

    // Every 30 minutes
    $schedules['every_thirty_minutes'] = array(
        'interval' => 30 * 60,
        'display'  => __( 'Every 30 Minutes' ),
    );

    return $schedules;
}
add_filter( 'cron_schedules', 'toptut_add_cron_intervals' );

Once registered, the custom schedule name (every_five_minutes) can be used in any wp_schedule_event() call as the recurrence parameter.